In REST terminology when a request is made to a URI, that request is asking for a representation of that resource. As developers it's more typical to think of these representations in terms of formats, extensions, and MIME types.
Our API attempts to respond to requests in the format for which the message asks.
Default Response Formats
Specifying a response format is completely optional. As architects of the API, we generally try to decide what is the most "natural" representation of a resource but this is only an arbitrary guideline.
For every resource that supports it, the default format is assumed to be XML. For any resource which does not have an XML representation, the default will be the first supported format listed. When in doubt, make a call to the service and see what's returned.
You can always take control of the situation by specifying the format in which you'd like the response.
Specifying the Format
Telling the API which format to serve your request can be accomplished in one of three ways:
HTTP Header Method
Send an HTTP
Accept header as part of the request, e.g.:
Although the HTTP protocol supports multiple formats listed in the
Accept header, our API will only take one. If an
Accept header lists multiple formats, only the first format named will be processed. Any subsequent formats in the field will be ignored.
This method is widely considered the more semantically correct RESTful approach.
HTTP Parameter (or "Query String") Method
Send an HTTP parameter called "format" as part of the request, e.g.:
The above example demonstrates making an HTTP
GET request and specifying the format in the query string. Note that HTTP parameters can also be sent with other HTTP methods such as
Append the format to the end of the path as an extension (but before any other query string parameters), e.g.:
Although this method is often considered the least RESTful, in practice it is widely adopted in REST-styled APIs throughout the web and thus accepted by our system.
Pro Tip: Most browsers will pass an
Accept header of
text/html by default, which will throw an error for most of our services because they don't serve any HTML representations.
To override this, use the query string method as noted above so you can see the results in your browser or use a tool such as the free Firebug plugin for Firefox that lets you set HTTP headers. Please note that the FAA does not officially endorse any of these products.
In general, the methods for specifying the format may be used interchangeably. However, if a request uses multiple methods simultaneously, then the HTTP parameter (query string) takes precedence and the HTTP
Accept header will be ignored.
This is to facilitate viewing of web service requests in web browsers, which will typically assign their own HTTP
Accept headers with formats usually not typically served by our API (e.g.,
text/html). Preferring the query string allows consumers to manually override that default behavior.
It's only necessary to employ one method per request.
In most cases where MIME types are unambiguous, a short name can be used instead of the full MIME type. For instance,
application/xml may be shortened to
application/json may be shortened to
json. This may not apply to all formats served by the API, so be sure to test your code.
Bad Response Formats
If you specify an invalid response format, such as requesting
image/png for a resource that only serves
application/json, the API will respond with a status code of
400 Bad Request.
See HTTP response codes and errors for more information.