NAV Navbar

Introduction

Server base url :

https://app.fallound.com/api/{endpoint}

All requests require stated headers:

{
  "Content-Type": "application/json",
  "Accept": "application/json"
}

Welcome to the Fallound APP API Documentation! This documentation describes the Fallound's API for mobile app use and integration.

You can view code examples in the dark area to the right, The examples are Json Objects that the API require for Server client Communication.

Each Example has a request that the client sends to the Server and a Response from the server.

Authentication

To authorize, use this header:

{
  "Authorization": "Bearer TestOauth2Token"
}

Make sure to replace TestOauth2Token with your API token.

Fallound uses Oauth2 protocol to allow access to the API.

Fallound expects for the API token to be included in all API requests to the server except for the stated below in a header that looks like the following:

Authorization: Bearer TestOauth2Token

The Authorization token can be requested by the Register / Login / Social Login endpoint to login to Fallound and gain access to the API

Register

Endpoint:

API {endpoint}: "register"

Request:

{
    "first_name": "first name",
    "last_name":    "last name",
    "email":        "[email protected]",
    "password": "testpassword"
}

Successful Response:

{
    "status": "0 or 1 (integer)",
    "data": {
        "id": "User id in fallound app (integer)",
        "first_name": "first name",
        "last_name": "last name",
        "email": "[email protected]",
        "access_token": "Fallound Access Token",
        "refresh_token": "Fallound Refresh Token",
        "verified": "0 or 1 (integer)",
        "new": "0 or 1 (integer)"
    }
}

As a new user to Fallound you need to call the register endpoint and supply contact details as shown in the request example.

On a successful registration to Fallound the server responds with status 1 indicating a successful call with no errors in the registration process.

The response constitutes the contact details that you provided with the additions of:

id:

This is the user id that Fallound issue to personalize and track user within the application and API.

access_token:

This is the Oauth2 access token that will be needed to authorize the calls to the API.

refresh_token:

This is the Oauth2 refresh token that is used to refresh the access token of the user using the API.

verified:

Upon registration an email is sent to the user to be verified as a user of Fallound, this key returns 0 if the email of the user is still not verified with the link sent. And 1 if the email of the user is already verified.

new:

This indicates if the user registered is a returning user to fallound or a new user that is registering for the first time on the API.

The key returns 0 if the user is a returning user, 1 if the user is new

Login

Endpoint:

API {endpoint}: "login"

Request:

{
    "email":        "[email protected]",
    "password": "testpassword"
}

Successful Response:

{
    "status": "0 or 1 (integer)",
    "data": {
        "id": "User id in fallound app (integer)",
        "first_name": "first name",
        "last_name": "last name",
        "email": "[email protected]",
        "image_url": "User uploaded image Fallound relative url"
        "access_token": "Fallound Access Token",
        "refresh_token": "Fallound Refresh Token",
        "verified": "0 or 1 (integer)",
        "new": "0 or 1 (integer)"
    }
}

As a registered user to Fallound you need to supply your previously provided email and password to gain access to Fallound's API.

The response JSON is object is identical to the register Json Object except for:

image_url:

This is the relative url for the user profile image in Fallound. The user uploads the photo using the API (described below) and on login the user image is provided to the client as a URL to be parsed using:

Base URL: https://app.fallound.com/{image_url}

Social Login

Endpoint:

API {endpoint}: "social-login"

Request:

{
    "email": "[email protected]om",
    "first_name": "first name",
    "last_name": "last name",
    "platform_id": "facebook unique user platform id",
    "platform": "fb",
    "access_token": "facebook's provided access token"
}

Successful Response:

{
    "status": "0 or 1 (integer)",
    "data": {
        "id": "User id in fallound app (integer)",
        "first_name": "first name",
        "last_name": "last name",
        "email": "[email protected]",
        "image_url": "User uploaded image Fallound relative url"
        "access_token": "Fallound Access Token",
        "refresh_token": "Fallound Refresh Token",
        "verified": "0 or 1 (integer)",
        "new": "0 or 1 (integer)"
    }
}

As a new or registered user to Fallound you can use a social Platform like facebook to Login and be authorized on Fallound's API

We will discuss the flow for Facebook login.

After authorizing the login with Facebook login portal usng facebooks's SDKs or API

Fallound expects a json object as in the example on the right.

platform_id:

This is the unique id that facebook assigns to you as their user.

platform:

This is used by Fallound's API to differentiate between social platforms.

for Facebook: fb

access_token:

This is the access token that facebook supplied to the client, this is used to authorize the user on Fallound by checking the authenticity of the token.

Interests

Fallound's basis is your interests. The interests is where the magic happens to get all your favorite podcasts and episodes.

In this section we will discuss getting all of Fallound's interests, updating your interests and getting your interests.

Get interests

Endpoint:

API {endpoint}: "interests"

Successful Response:

[
    {
        "id": "interest's id",
        "name": "name",
        "image_url": "relative image url"
    },
    ...
]

This is a GET request on the endpoint shown on the right.

The request responds with a json array of interest objects, where the objects contain:

image_url:

This is a relative url for the image of the interests it is used after:

base url: https://app.fallound.com/{image_url}

Get user interests

Endpoint:

API {endpoint}: "user-interests"

Successful Response:

{
    "interests": "an array of interest ids"
}

This is a GET request on the endpoint shown on the right.

The request responds with a json array of interest ids.

Update user interests

Endpoint:

API {endpoint}: "user-interests"

Request:

{
    "user_id":  "Fallound's user id",
    "interests": ["array of interest ids"]
}

Successful Response:

{
    "status": "0 or 1 (integer)"
}

This is a PUT request on the endpoint shown on the right.

if the user interests are successfully updated Fallound responds with status 1, and 0 for any error.

Errors

The Kittn API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The kitten requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.