Designing RESTful representations

A resource can be represented in several ways. We’ll examine different strategies to return correct representations, and to avoid common mistakes.

Representing resources with HTTP headers

Some HTTP headers are commonly used to describe a resource. They must be added to the response, in order to represent that resource in a complete way.

Content-Type

It indicates the type of the resource, with its charset. Examples are text/plain, image/jpeg, application/pdf. Media types specify which format (PDF, JSON, XML) has been used to encode the body, and are used by clients to select proper parsing engines.

A server receiving a request without Content-Type, should return a 400 (Bad Request).

A client receiving a response without Content-Type should treat it as a bad response.

Content-Lenght

It specifies the size of the body (in bytes). HTTP 1.1 includes a more efficient mechanism known as chunked transfer encoding.

This header should be checked only if there is no Trasfer-Encoding: chunked.

Content-Language

This header specifies the language of localized representations. The RFC 5646 defines language and country code tags.

Content-MD5

This header includes an MD5 digest of the representation, to provide its consistency and integrity. The value is computed after applying content (i.e. gzip) but before transfer (i.e. chunked) encoding.

Content-Encoding

If the body is encoded, this header will contain how it has been encoded (i.e. compress, deflate or gzip). If the media type allows a charset parameter, you can include this header specifying the encoding used to convert characters to bytes.

If representations are JSON, XML or HTML data, let their parsers interpret the character set (see RFC 4627).

Also, avoid including a charset in Content-Type and a different one in the body, that would lead to encoding mismatch.

Last-Modified

It indicates the last time the resource was modified.

Choosing formats and media types

Media types and formats should be chosen in a flexible way, depending on use cases and client needs. The best place to find a standard format is the IANA (Internet Assigned Numbers Authority) Media Type Registry.

Use extensible formats if no standard media type and format is defined, such as XML (application/xml), Atom Syndication Format (application/atom+xml), or JSON (application/json).

Images or rich formats data should be used to provide alternative representations of data: when using such media types, add a Content-Disposition header, as in

to give hints on the file to save.

If a new format and/or media type must be used, register both with IANA, by following what’s described in RFC 4288.

Standard media types are:

Generic formats do not contain application-specific semantics, so they are customised for each representation they describe.

New formats and media types

Even if it’s best to use standard formats and media types whenever possible, sometimes new ones are required (i.e., when introducing a new video encoder, or a new document type). If such formats are widely available, new media types are strongly encouraged.

These are rules to follow:

• if media types are based on XML, the subtype should end with +xml.
• if media types are for private use only, the subtype should start with vnd..
• if media types are for public use, register them with IANA, as indicated in the RFC 4288.

Designing representations

When designing representations, there are some common points to keep, in order to make them exchangable. As general rules:

• add a self link (i.e. a link with a relation type self) to the resource, that’s equivalent to the request URIs or Content-Location headers;
• include identifiers for each domain entities that can be mapped to resources;
• specify the language if natural text is included in the representation.

XML example

Let’s suppose we are retrieving a task within a checklist. The XML request is:

and the relative response:

If a new task has to be created, the request will be

and the response

JSON example

Mapping the body of the last response in JSON, the result would be:

Collections

Collections are used to group a number of resources together, and to iterate through them. In order to simplify how to access to different sets of resources, some additional details can be added:

• a self link to the collection
• a link to the next page, if available
• a link to the previous page, if available
• the total size of the collection (this should be a hint, not the real number, which calculation could be very expensive)

Collections of similar objects (i.e. cars and boats) should be used when their members are structurally and semantically similar.

Portable data formats

Except for texts to be presented to end users, to make representations easily available for different applications, formats depending on language, region or country should be avoided. Instead, some standards will apply:

Entity identifiers

Use entity identifiers when links within the REST protocol can change, or when the same resources can be used outside the REST web service (i.e. for SOAP web services, or RPCs). They should be used also when resources are not a direct mapping of domain entities, and their uniqueness should be provided.

There is no established standard that defines these ids, but a common convention is to use a syntax like

Binary data

Sometimes we need to encode data that have no textual representation, such as a video or an image.

Avoid using base64 encodings, but instead use multipart media types such as multipart/form-data, multipart/mixed, multipart/related or multipart/alternative (see here).

Another way to handle different media types is to provide links to separate resources.

Returning errors from server

Errors are another way to express the result of an HTTP exchange between a client and a server. They are usually composed of a status code, headers and a content body, just like any other response.

Errors due to clients are mapped with 4xx status codes, while 5xx represent server errors.

Response bodies should contain a description of the error in plain text or HTML, properly formatted and localized.

A link (with the Link header or some anchor within the body) could direct to an informational resource, even with debug notices. An error identifier can be used when reporting problems.

One common mistake is to return a successful status code (2xx or 3xx) with an error described in the body. Avoid this to help cache servers, proxies and clients parse correct responses.

4xx: client errors

This is a mapping of errors due to client behavior:

5xx: server errors

The only available server errors to map are:

Error bodies

The error message should contain a body for all methods except HEAD. In all the other cases, there should be

• a short description of the error condition
• a longer description with steps on how to fix the error, if possible
• an error identifier
• a link to help resources

Handling errors in clients

Clients has to handle two different kind of errors: network failures and server responses. The first type is usually handled with custom exceptions, the latter with explicit coding. The following table shows how each error should be treated:

Errors should be handled as resources, not exceptions, since they contain useful informations to be managed.

Related Posts

Handling REST resources

REST guidelines