Safari Books Online is a digital library providing on-demand subscription access to thousands of learning resources.
- Create BookmarkCreate Bookmark
- Create Note or TagCreate Note or Tag
- DownloadDownload
- PrintPrint
4. Metadata Design > 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.
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;format="http://api.formats.wrml.org/application/json";
schema="http://api.schemas.wrml.org/soccer/Player"
-
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
Playerresource 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.
Note
See Media Type Representation, which describes how this media type’s format and schema documents should be represented.
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.
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.
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:
http://api.schemas.wrml.org/soccer/Player-2
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:
http://api.schemas.wrml.org/soccer/Player
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.
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";
schema="http://api.schemas.wrml.org/soccer/Team" -
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.
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.
Warning
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.
