Overview: Urban Airship API Version 3

Version 3 of the Urban Airship Push API is a major update which unifies several legacy endpoints into two— one for sending messages and one for scheduling. We’re excited about what this means for our customers because the structure of the API both simplifies existing integrations and paves the way for rapid feature development during the next wave of the Urban Airship Product Road Map.

Please take a moment to take a look at some of the important details below.

API Request Format

All API requests are HTTP requests, using the base url https://go.urbanairship.com/. For all requests with a body, the body must be in JSON format. When sending a request with a JSON body, set the Content-type header to application/json.

Authentication

API requests are identified using HTTP basic authentication. The username portion is the application key. The password portion is either the application secret, or master secret. The application secret is restricted to certain low-security APIs, as it is intended to be included in the distributed application. The master secret is needed for sending messages and other high-value requests, and as such must be guarded carefully.

Warning

Never embed the master secret in an application you distribute.

Date/Time Format

All date/time values are represented according to ISO 8601 in UTC. A T separator is preferred but not required; it will be included in all date/time values generated by the API.

API Response Format

All API responses are HTTP responses, making use of appropriate HTTP response codes. When a body is present, it will usually be in JSON format.

When a request results in a return value containing multiple entities, they SHALL be contained in an array-valued attribute, the name of which MAY vary by endpoint. For example, /api/tag will return a list of tags in the "tags" attribute, while /api/schedules will return a list of schedules in the "schedules" attribute.

When a request contains multiple input entities, such as batch push, the response will return the resulting response entities in the same order as their corresponding inputs.

Example push response:

HTTP/1.1 202 Accepted
Content-type: application/vnd.urbanairship+json; version=3; charset=utf8;
Data-Attribute: push_ids
{
    "ok" : true,
    "operation_id" : "5c5c6a11-3e63-4c52-9a75-4677702f2c18",
    "push_ids" : [
        "2f2fb168-710e-1596-f678-d7dd6c19adea",
        "88438e81-bb31-82a9-5feb-e7fd5b21ca7e",
        "10665229-e8bc-4606-7c98-d4b7fb82a97b"
    ]
}

Response Codes

The API makes use of standard HTTP response codes, with standard HTTP semantics. Response codes in the 200 range indicate success. Codes in the 400 range indicate errors of a correctable nature, and codes in the 500 range indicate system errors.

In the event of an error, the response body will contain an error object.

Summary

200 OK:Nice work!
201 Created:An API request to create a new entity or entities was successful, the entities were created.
202 Accepted:An API request has been successfully accepted into a processing queue to be acted on later.
204 No Content:An API request was successful, but there’s no response body to return. Often seen on successful DELETE calls.
400 Bad Request:Parsing or validating the request failed
401 Unauthorized:Authentication information (the app key & secret) was either incorrect or missing
403 Forbidden:Authentication was correct, but the user does not have permission to access the requested API (for example, if the feature in question is not included in the customer’s pricing plan).
404 Not Found:Returned when a request is made for a non-existent entity.
405 Method Not Allowed:Returned when a request is made using an HTTP method not supported by the endpoint. For example, sending a DELETE to /api/schedules.
406 Unacceptable:Return when the client requests a version of the API which cannot be satisfied, because no compatible version is currently deployed.
410 Gone:The requested resource is no longer available on this server and there is no forwarding address.

Error Object

Error objects are used in API response to indicate something went wrong. An error object is a JSON dictionary with the following attributes:

  • "ok" - false
  • "error" - A simple human readable string
  • "error_code" - A numeric code indicating the specific error condition
  • "details" - A JSON dictionary indicating where the error occurred in the JSON parsing, if available, and further information about the nature of the error.

Examples:

{
    "ok" : false,
    "operation_id" : "da714684-cd89-fd14-7b51-6f623efa07c0",
    "error" : "Invalid push content",
    "error_code" : 40001,
    "details" : {
        "error" : "Yo dawg, that value ain't kosher",
        "path" : "push.wns.text[2]",
        "location" : {
            "line" : 47,
            "column" : 12
        }
    }
}

Note

When writing your application, it’s a good idea to log whenever you receive a non-2XX response. For best results, log the request and response headers as well as the request and response body. This will give you the most information to fix the problem or to contact support.

Versioning

Beginning with API v3, you must specify the API version with the Accept HTTP header. At this time, version 3 is the only supported version number.

Versioning Syntax

You must specify the version of the API you are using with the Accept HTTP header. If you do not specify an API version in the Accept header, a 406 Not Acceptable is returned.

The content type used is a vendor-specific media type (see RFC 4288), of the form:

application/vnd.urbanairship+(format); version=(version);

The default content type is:

application/vnd.urbanairship+json; version=X

Example:

Accept: application/vnd.urbanairship+json; version=3;

Return Codes

If the API service cannot satisfy an API version requested by a client (i.e. the version is too old, and no forward-compatible version is available), the API will return a 406 Not Acceptable response.