Responses

All responses to requests to the App.net API endpoints listed under Resources, whether successful or not, will be returned in the same type of envelope structure. This document describes how that envelope works and what it may contain.

The authentication endpoints return a slightly different format that follows the OAuth2 specification.

Response Envelope

The top-level response is an object containing two keys. The first key, data, corresponds to the actual response item requested. This may either be an object itself or a list of objects. The particular data returned is described in each endpoint’s documentation. If the request is unsuccessful (results in an error), no data key will be present.

The second key present, meta, corresponds to an object containing additional information about the request. This object will always contain code, a copy of the HTTP status code that has been returned. It will also contain pagination metadata and/or a stream marker when relevant.

Sample Response Envelope

{
  "data": "the data you requested",
  "meta": {
    "code": 200,
    "marker": {
      "id": "1",
      "name": "global",
      "percentage": 0,
      "updated_at": "2012-11-09T23:35:38Z",
      "version": "NWoZK3kTsExUV00Ywo1G5jlUKKs"
    },
    "max_id": "65039",
    "min_id": "65039",
    "more": true
  }
}

JSONP

We support JSONP for easy, unauthenticated cross-domain API requests with wide browser support. Normal JSON responses are wrapped in a Javascript function so they may be included in a webpage and fetched directly by the browser via a script tag. It is not possible to make requests to API endpoints which require authentication with JSONP.

To use JSONP, add a callback parameter to the request’s query string. For example:

https://alpha-api.app.net/stream/0/posts/stream/global?callback=awesome

Will result in a response that looks something like this:

awesome({...})

When using JSONP, our servers will return a 200 status code in the HTTP response, regardless of the effective status code.

For more information on JSONP, see the Wikipedia page for JSONP.

CORS

We support CORS for authenticated cross-domain API requests direct from browsers. Support for CORS may vary by browser. When using CORS, you are still responsible for obtaining, storing and supplying a valid access token with each request, if access to authenticated endpoints is required. For more information on CORS, see the Wikipedia page for CORS.

Pretty-printed JSON

We return a minified form of JSON by default, but support pretty-printing of JSON for debugging and enhanced readability. Note that pretty-printed JSON contains a trailing line break, so you may wish to make sure your JSON decoder handles this properly.

To request pretty-printing, send the following HTTP header with your request:

X-ADN-Pretty-JSON: 1

Sending any value is sufficient. Omit the header entirely if you wish to receive minified JSON.

Error Conditions

If the request was unsuccessful for some reason, no data key will be returned – the response object will only contain a meta object. Additional information pertaining to the type of error generated will be returned inside the meta object. In particular, the code and error_message keys will point out what sort of error occurred. There may also be a uniquely-identifying error_slug and error_id present that can be used to get more information about the error and which may be helpful in support requests with App.net staff.

Error Slugs

Slug Relevant on Description
invalid-token global The passed OAuth token was not valid. It may have been corrupted or missing some of its data
not-authorized global The User for the given token has likely explicitly revoked access to your App. You may wish to reauthenticate that User.
token-expired global The passed token (or code) has reached the end of its lifetime. A new token will have to be generated.
code-used access_token The passed OAuth code was already used to generate a token.
redirect-uri-required access_token The call to access_token must include redirect_uri.

Possible HTTP status codes

App.net uses the HTTP status code to indicate if an API request was a success or failure. For environments that can’t access the raw HTTP response directly, this value is also duplicated in the meta.code value. The following table lists all currently used HTTP status codes. If you get a status code that is not documented below, please open an issue.

Code Description
200 OK The request was successful.
204 No Content Returned when retrieving an incomplete file or when uploading file content to an incomplete file.
302 Found Redirection to the final destination of a resource. Returned when retrieving file contents, user avatar, or a cover image.
400 Bad Request The API request was malformed in some way. A message should be returned that indicates how this request can be fixed.
401 Unauthorized A token is required. If you passed a token, a message should indicate why this token is not authorized. The error slugs should also provide a reason why this token is invalid.
403 Forbidden The token you are providing doesn't have the right to perform the request. Please check that your token is of the correct type and has the required scope.
404 Not Found The requested resource was not found.
405 Method Not Allowed The HTTP method requested is not allowed. Please see the Allow header for a list of acceptable HTTP methods.
429 Too Many Requests The request could not be completed due to a rate limit. Please wait at the number of seconds specified in the Retry-After header before you retry this request.
500 Internal Server Error An unexpected server error has occurred and the App.net team has been notified.
507 Insufficient Storage The request couldn't be completed because the authorized user has hit a quota limit. This could be returned when trying to upload a file or when a user on a free account tried to follow more users than their plan allows. The data.limits and data.storage attributes of the current token information can help an app avoid this error.