Response Formats

About Formats

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 two ways:

HTTP Parameter (or "Query String") Method

Send an HTTP parameter called "format" as part of the request, e.g.:

http://services.faa.gov/airport/status/IAD?format=application/xml

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 POST.

HTTP Header Method

Send an HTTP Accept header as part of the request, e.g.:

Accept: application/xml

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.

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.

Conflicting Methods

In general, the two methods for specifying the format may be used interchangeably. However, if a request uses both 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 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 do one or the other - not both.

Short Formats

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 xml and 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/xml and application/json, the API will respond with a status code of 400 Bad Request.

See HTTP response codes and errors for more information.