REST Pub API: HTTP requests
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.
Most of the API endpoints support JSONP invokes with the inclusion of a
callback query parameter. For example:
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.
All HTTP requests to public endpoints must specify the required response format (media/content type) in one of two ways:
By including a
formatrequest query parameter with a value, such as
By including the expected response format in the HTTP
Acceptrequest header. For example,
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.
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
PresenterID) are not returned.
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.
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.