O'Reilly logo

REST API Design Rulebook by Mark Masse

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Media Type Design

Client developers are encouraged to rely on the self-descriptive features of a REST API. In other words, client programs should hardcode as few API-specific details as possible. This goal influences many aspects of a REST API’s design, including opaque URIs, hypermedia-based actions with resource state awareness, and descriptive media types.

Rule: Application-specific media types should be used

REST APIs treat the body of an HTTP request or response as part of an application-specific interaction. While the body may be formatted using languages such as JSON or XML, it usually has semantics that require special processing beyond simply parsing the language’s syntax.

As an example, consider a REST API URI such as http://api.soccer.restapi.org/players/2113 that responds to GET requests with a representation of a player resource that is formatted using JSON. If the Content-Type header field value declares that the response’s media type is application/json, it has accurately conveyed the body content’s syntax but has disregarded the semantics and structure of the player representation. The response’s Content-Type header simply tells a client that it should expect some JSON-formatted text.

Alternatively, the response’s Content-Type header field should communicate that the body contains a representation of a player document that is formatted with JSON. To help achieve this goal, the WRML framework, which was introduced in the section WRML, uses a descriptive media type: application/wrml. The example below shows WRML’s media type used to describe a player form that is formatted using JSON:

# NOTE: the line breaks below are for the sake of visual clarity.

application/wrml;  1
    format="http://api.formats.wrml.org/application/json";  2
    schema="http://api.schemas.wrml.org/soccer/Player"   3

The WRML media type.[34]


The required format parameter’s value identifies a document resource that describes the JSON format itself.


The required schema parameter’s value identifies a separate document that details the Player resource type’s form, which is independent of the media type’s format parameter’s value.

This media type may appear excessive when compared to simpler ones like application/json. However, this is a worthwhile trade-off since this media type communicates—directly to clients—distinct and complementary bits of information regarding the content of a message. The application/wrml media type’s self-descriptive and pluggable design reduces the need for information to be communicated out-of-band and then hardcoded by client developers.


See Media Type Representation, which describes how this media type’s format and schema documents should be represented.

Media Type Format Design

Most media types identify a format using a simple string, like application/json. Instead, by using a format parameter with a URI value, the WRML media type directs client programs to a cacheable document that provides links to other documents related to the format. In the example above, the representation of the document referenced by the format parameter (http://api.formats.wrml.org/application/json) contains links to related web resources, such as http://www.json.org and http://www.rfc-editor.org/rfc/rfc4627.txt.

More importantly, by leveraging REST’s code-on-demand constraint, the format document’s representation can provide links to formatting and parsing code, which clients can download and execute to serialize and deserialize an HTTP message body’s content. By providing this code, available for various programming languages and runtime environments, an API can programmatically teach its clients how to interoperate with its representation formats. The future-proof nature of this design may prove especially useful when a REST API wishes to adopt a new format that is not yet widely supported by its clients.

The section Rule: A consistent form should be used to represent media type formats, outlines the structure of a format document’s representation.

Media Type Schema Design

As discussed next in Chapter 5, a resource’s state representation consists of fields and links. For a given “class” of resource, the set of expected fields and context-sensitive links can be described by a schema document. The WRML media type’s schema parameter references a cacheable schema document, which describes a resource type’s fields and links; independent of any specific representational format. This separation of concerns allows multiple representation formats to be negotiated by clients and supported by REST APIs with relative ease. With a set of standard primitive types, outlined in Field Representation, a schema document can describe a resource representation’s fields in a format-independent manner.

The section Rule: A consistent form should be used to represent media type schemas, details the structure of a schema document’s representation.

Media Type Schema Versioning

The different versions of a given schema should be organized as different schema documents, with distinct URIs. This design is borrowed from the approach traditionally used by the W3C[35] and IETF[36] for versioning the URIs of Internet Drafts on their way to becoming approved standards. The example below shows the URI of a schema document that details the fields and links of a soccer Player resource type:


The -2 suffix designates the version number of the Player resource type’s schema. As a rule, the current version of the resource type’s schema should always be made available through a separate resource identifier, without a numeric suffix. The example below demonstrates the design of the Player resource type’s current schema URI:


The URI of a resource type’s current schema version always identifies the concept of the most recent version. A schema document URI that ends with a number permanently identifies a specific version of the schema. Therefore the latest version of a schema is always modeled by two separate resources which conceptually overlap while the numbered version is also the current one. This overlap results in the two distinct resources, with two separate URIs, consistently having the same state representation.

Rule: Media type negotiation should be supported when multiple representations are available

Allow clients to negotiate for a given format and schema by submitting an Accept header with the desired media type. For example:

# NOTE: the line breaks below are for the sake of visual clarity.

Accept:  application/wrml;
             format="http://api.formats.wrml.org/text/html";   1
             schema="http://api.schemas.wrml.org/soccer/Team"  2

Using media type negotiation clients can select a format.


Using media type negotiation clients can select the schema version that will work best for them.

Additionally, to facilitate browser-based viewing and debugging of a REST API’s responses, consider supporting raw media types as shown in the example below:

Accept:  application/json

This will allow web browser add-ons such as JSONView to render a REST API’s responses as JSON.

Rule: Media type selection using a query parameter may be supported

To enable simple links and easy debugging, REST APIs may support media type selection via a query parameter named accept with a value format that mirrors that of the Accept HTTP request header. For example:

GET /bookmarks/mikemassedotcom?accept=application/xml

This is a more precise and generic approach to media type identification that should be preferred over the common alternative of appending a virtual file extension like .xml to the URI’s path. The virtual file extension approach binds the resource and its representation together, implying that they are one and the same.


Media type selection (or negotiation) via a query parameter is a form of tunneling that conveys metadata in the URI rather than in HTTP’s intended slot: the Accept header. Therefore it should be used with careful consideration.

[34] The application/wrml media type’s IANA registration is pending, see http://www.wrml.org for the most up-to-date information.

[35] World Wide Web Consortium (W3C), http://www.w3.org.

[36] The Internet Engineering Task Force (IETF), http://www.ietf.org.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required