Application API

#General API Structure

The World Singles API has a base URL (slightly different for QA and production - see below) followed by an action. Most API endpoints are restricted to either GET (non-destructive) or POST (destructive / mutating). GET endpoints accept regular query parameters as part of the URL. POST endpoints accept plain text parameters passed as if part of a simple form POST operation.

• Results are always JSON structures.

• Success of any operation returns an HTTP status code of 200.

• Failure of any operation returns an HTTP status code in the 400-499 range (but mostly 403 Forbidden). For a failure, the body is a JSON structure with a key, fail, which may provide more detail about why the request was forbidden. For example, if required arguments to an action are missing, you’ll get 403 Forbidden with a body specifying fail as "Invalid Argument". Optionally, there may be a key failcode, which will be an array of failure codes (numeric values). See the individual API call documentation for a list of possible failure codes.

As of October 2015, the World Singles API has adopted OAuth 2 as the security protocol. Public API endpoints can be called without going through OAuth 2 security. All other endpoints require an Authorization header to be passed with the OAuth 2 access token specified as the Bearer in that header. We use JWT - JSON Web Tokens - for various tokens involved in the OAuth 2 process. Interacting with our OAuth 2 server, in order to obtain an access token is described in OAuth 2 Authentication.

In addition to authentication via our OAuth 2 server, when you register a new user (using the /users API), the result will include an authorization code which you will need to exchange for access and refresh tokens, via the Authorization Server.

If, during an authenticated session, a user is suspended or deactivated, the next API call will fail with 403 Forbidden and fail will be "Suspended" or "Deactivated" respectively. A suspended user will need to contact our Customer Service team in order to regain access to their account. A deactivated user may choose to reactivate their account when they next login. In both cases, the client application should forget the access and refresh tokens and re-initiate the authentication process.

The ID of the site for which your client application intends to operate will be hardcoded into your application and provided to the API for any operations that accept siteid, including authentication. For testing, your can use http://st.desikiss.com as the corresponding desktop web application which is site ID 54. World Singles will provide additional site IDs as needed during the development process.

#Base URLs