REST Pub API: HTTP requests

This article outlines important notes when writing code that makes HTTP requests to public API endpoints. This article is applicable to developers writing server code that invokes API endpoints, as well as developers writing JavaScript code in web browsers.

Cross-Origin Resource Sharing (CORS) support

All public API endpoints support CORS security headers in HTTP requests and responses. This standard is relevant specifically to developers writing JavaScript API code in web browsers. Support for this standard enables painless cross-domain requests from JavaScript in modern web browsers (IE10+, Firefox 3.5+, Chrome 4+, Safari 4+, Safari on iOS). For more information about other browsers (such as IE8/9), see CORS support in legacy browsers and platforms.

For older web browsers such as IE9 and earlier, the API supports JSONP as a CORS alternative for cross-domain requests. This standard is considerably more limited, particularly for robust error handling options, and can be used only for HTTP GET requests.

Our strong recommendation is to allow all JavaScript code to use CORS requests to cover the majority of browsers, with specific legacy fallbacks for IE9 and IE8 where these features aren't available (or don't work properly).

JSONP support

Most of the API endpoints support JSONP invokes with the inclusion of a callback query parameter. For example:

GET https://api.example.org/api/2012-02-01/pub/resources/presenters/10569/?fields=PresenterID,FullName&callback=myCallback

For general details on handling JSONP responses, including success and failure scenarios, see JSONP response codes.

Specific details on JSONP support and usage syntax are also documented in the articles for each endpoint.

Content types

All HTTP requests to public endpoints must specify the required response format (media/content type) in one of two ways:

• By including a format request query parameter with a value, such as format=json

• By including the expected response format in the HTTP Accept request header. For example, Accept: application/json

Requests that do not specify a required response format will receive a HTTP 406 Not Acceptable response.

More information about response types, error codes, and content can be found in the API Responses article.

Fields

All endpoint requests must specify a list of fields required in the response payload by including a fields query parameter in the request. A list of the supported fields is available in each endpoint's respective articles.

This opt-in design for fields allows the API to be forward compatible with future modifications where additional fields may be added to and endpoint specification (but not returned by default), and also improves performance by explictly having the client indicate the required fields and returning only those in the response payload.

For example, when using the Presenters resource, if the client requires only a list of presenter names (FullName field) and links to pages (ViewUri field), the following fields parameter value can be used: ?fields=FullName,ViewUri. All other supported fields (such as Profile, SocialNetworkInfo and PresenterID) are not returned.

Query parameters

Parameters passed in querystrings for HTTP GET requests must be properly URI encoded to ensure special characters are appropriately encoded over the wire. This is important for facet and filter values which often contain values with characters specified by users.

The builtin javascript method encodeURIComponent can be used to encode strings for use in a URI. Special characters which must be handled (encoded) include the space character, \ / ? # + plus any extended UTF-8 symbol characters not in the ASCII character set.

Recommended best practice is to encode all value strings being used in HTTP GET queries.