API Development

API Development

At times, you need to expose the data layer of your application to ensure the same interactions provided in a web page can be performed by a device.

This may require authentication, content submission, workflow and much more.

At minimum, it’s essential (yes – essential) that the APIs are consistent in the way they accept input as well as how they convey status, otherwise the consumer of the API will be dealing with exceptions much as we do in English; e.,g. an apostrophe is a contraction for a word and is except with the words it is.

At AOL we exposed a tremendous amount of data via RESTful API to enable other systems to use content without having to syndicate or provide copies of it. The advantage of this approach is that the highest quality data was always available (not a stale copy) so if a movie at a theater sold out, it would be immediately apparent in the data returned by the API.

One thing that differentiated Moviefone/777-FILM’s information from show times printed in a newspaper was that as the theater managers rescheduled movies to other auditoriums and times based on popularity, Moviefone would be updated and what newspapers would be out of date. That’s the benefit of an API.

What follows is an example of a single API that provisions the user with rights or privileges for the continued use of other APIs.

API: Create  Token

Objective:

Create a token permitting a user to interact with the application platform based on their privileges where:

  • A known authenticated user gets all access and rights granted upon successful login
  • Any other user is given a token allowing them privileges granted an anonymous user

Verbs:

  • Create – http POST

Example:

https://api.nyprnewco.com/token

Post Arguments

Field C R U D S Length Description
username Y n/a n/a n/a n/a 128 max string user name or email (either will suffice)
password Y n/a n/a n/a n/a 128 max string password
callback O n/a n/a n/a n/a string Optional. The name of your JavaScript callback function.

Inferred Arguments:

  • IP:  IP Address submitting the request – May be from X-Forwarded-For (If service is behind a proxy/load balancer – which is 99.9999% likley.)

Response

Note: if callback is provided as an optional argument, the results illustrated below will be returned within the callback string provided for execution of a JavaScript function; e.g. callback=”MyCallbackFunc” will return something similar to:

MyCallbackFunc({…the success or failure response contained in curly braces you see below…});

Success

{
    "status": 1,
    "t":"NYPRb7kTNewCo2lqCYzvaA==",
    "ip": "98.116.218.88",
    "username":"johndoe",
    "userId":"4851902",
    "email":"johndoe@email.com"
}

Failure

{
    "status": -1,
    "errorId": "404",
    "error": "Not Found: Username, email or password invalid"
}