Protocols/WebAPI/Reference/Methods
| WebAPI Protocol |
| Basic |
| Introduction |
| Clients |
| Whimsicals |
| Host Interaction |
| Flow |
| Authentication |
| • Client |
| • WebApp |
| Other Services |
| • |
| Foodgroups |
This section contains methods supported by the Web AIM API. All of our methods that do not return raw data support both JavaScript Object Notation (JSON) and Simple XML output, so the developer can choose whichever is easier. JSON is a lightweight data-exchange format used by many popular web services. (To learn more about JSON, see JSON.org, as well as the resources linked to from JSON's Wikipedia page.)
Almost every method supports 3 standard parameters:
- f (required) to select the format of the returned data
- r (optional) to include a request Id that is returned with the results
- c (optional) to specify a JSONP callback in the returned results
All of the output is wrapped in shared wrappers which contain the statusCode, statusText, an optional statusDetailCode and if provided in the request, the matching requestId. The HTTP Status Code will always be 200, unless a format parameter is missing, and instead results for the request are contained inside the statusCode field returned in the wrapper.
The JSON standard wrapper looks like this:
{"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
...
}
}
}
The Simple XML standard wrapper looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusOk>
<requestId>123</requestId>
<data>
...
</data>
</response>
Requests are sent to Web AIM through simple APIs. Each method is appended to the base URL and arguments are passed as parameters. Responses are sent back in Simple XML or JSON formats. If the command sent contained the optional callback parameter 'c', that parameter is prepended to the wrapped JSON literal resulting in a valid JavaScript function call; this is known as JSONP format.
For example, a developer might wish to use the Web AIM API's getToken method to determine whether a visitor has signed in, and if so, obtain an authentication token. The developer takes the base URL for the getToken method, https://api.screenname.aol.com/auth/getToken, and adds his developer key and desired output format, JSON, as parameters. They would like the API response to be parsed by a function, 'authenticate', so they add that as the callback parameter. The full API request looks like this:
https://api.screenname.aol.com/auth/getToken?f=json&k=MYKEY&c=authenticate
If the visitor hasn't signed in, the response from the Web AIM API might look like this:
authenticate({
"response":{
"statusCode":401,
"statusText":"Authentication Required",
"data":{
"redirectURL":"http://api.screenname.nina.biz/auth/login"
}
}
});
This is valid JavaScript. If placed in a script tag and dynamically inserted into the head of the document, it will execute, calling the function specified in the callback parameter - in the above example, 'authenticate'. This is one of JSON's chief advantages; properly padded, it allows developers to dynamically introduce data from other domains without resorting to server-side code.
Since events from the Web AIM API can arrive asynchronously at the client, they are received by performing a long poll on special fetchEvent service. The fetchEvent service waits until there are events ready to be received or a timeout has occured; when a timeout occurs, the caller simply begins a new fetchEvent.