Representation Design

In this post I relate to you how components are represented in REST APIs and outline how to do the in a standard and meaningful way. There four key aspects to consider while thinking about representational design. In each aspect, I have tried to explain the rules that govern what kind of forms and formats are to be used.

1. Message Body Format

REST APIs often employ a text-based format to represent a resource state as a set of meaningful fields. Today, the most commonly used text formats are XML and JSON.

Following are some rules regarding the format of the Message Body

• Rule: JSON should be supported for resource representation

As a format for data exchange, JSON supports lightweight and simple interoperation:it does its job. Today, JSON is a popular format that is commonly used in REST API design. JSON borrows some of JavaScript’s good parts and benefits from seamless integration with the browser’s native runtime environment.

• Rule: JSON must be well-formed

A JSON object is an unordered set of name-value pairs. The JSON object syntax defines names as strings, which are always surrounded by double quotes. The following example shows this;

{
	"firstName" : "Osvaldo",
	"lastName" : "Alonso",
	"firstNamePronunciation" : "ahs-VAHL-doe",
	"number" : 6,
	"birthDate" : "1985-11-11"
}

• Rule: XML and other formats may optionally be used for resource representation

REST APIs may optionally support XML, HTML, and other languages as alternative formats for resource representation.

• Rule: Additional envelopes must not be created

A REST API must leverage the message “envelope” provided by HTTP. In other words, the body should contain a representation of the resource state, without any additional, transport-oriented wrappers.

2. Hypermedia  Representation

Hypermedia, an extension of the term hypertext, is a nonlinear medium of information which includes graphics, audio, video, plain text and hyperlinks. Hypermedia may be developed a number of ways. Any programming tool can be used to write programs that link data from internal variables and nodes for external data files.

In his thesis, Roy Fielding describes four interface constraints for REST. These are

1. identification of resources through URIs
2. manipulation of resources through their representations
3. self-descriptive representations
4. hypermedia as the engine of application state.

The rationale behind this fourth constraint is that, by embedding actions controls and URIs within each representation, the client remains independent of the server, and therefore can be universal. The representation that the client receives would include possible new state changes, the URIs and methods that could be used for those transitions, and any associated ordering semantics.

The idea of hypermedia embedding all the action controls necessary to interact with the server works well for an arbitrary number of universal clients interacting with a given server. In this case, the server offering a set of resources specifies all the ordering/interaction rules within the representation.

Most application clients, on the other hand, interact with more than one server, and any given server cannot set the ordering constraints. The clients know how to compose applications out of resources offered by various servers, and each client needs to be able to exercise control over composition. To be able to exercise such a control, client applications cannot be universal, and the benefits that John lists above cannot be completely realized.

• Rule: A consistent form should be used to represent links
• Rule: A consistent form should be used to represent link relations
• Rule: A consistent form should be used to advertise links
• Rule: A consistent form should be used to represent media type formats

3. Media Type Representation

Programmers working with the Web are familiar with modeling informational in multiple domains and formats a structured representational form, which is carried by an individual HTTP request or response message body, is analogous to an instance of a schema class

• Rule: A consistent form should be used to represent media type schemas

1. Document
2. Class
3. Storage
4. Controller

• Rule: A consistent form should be used to represent media type schemas

4. Error Representation

HTTP’s 4xx and 5xx error status codes should be augmented with client-readable information in the response message’s entity body. The following rules present consistent forms pertaining to errors and error responses.

• Rule: A consistent form should be used to represent errors
• Rule: A consistent form should be used to represent error responses

Media Types in RESTful APIs

A typical REST API will most often work with media types that fall under the application type. As applications become content-rich, it is imperative that APIs should be designed to incorporate all kinds of media effectively.

The media type syntax is as follows

type “/” subtype *( “;” parameter )

The type value may be one of: application, audio, image, message, model, multipart, text, or video.

Content-type: text/html; charset=ISO-8859-4

Content-type: text/plain; charset=”us-ascii”

The Internet Assigned Numbers Authority (IANA) governs the set of registered media types and provides links to each type’s published specification (RFC). The IANA allows anyone to propose a new media type by filling out the “Application for Media Type” form (http://www.iana.org/cgi-bin/mediatypes.pl.)

Some commonly used registered media types are listed below:

• text/plain
  • A plain text format with no specific content structure or markup.
• text/html
  • Content that is formatted using the HyperText Markup Language (HTML).
• image/jpeg
• An image compression method that was standardized by the Joint Photographic Experts Group (JPEG).‖
• application/xml
  • Content that is structured using the Extensible Markup Language (XML).
• application/atom+xml
• Content that uses the Atom Syndication Format (Atom), which is an XML-basedformat that structures data into lists known as feeds.
• application/javascript
  • Source code written in the JavaScript programming language.
• application/json
• The JavaScript Object Notation (JSON) text-based format that is often used by programs to exchange structured data.

Media types use the subtype prefix “vnd” to indicate that they are owned or controlled by a “vendor.” Vendor-specific media types convey a clear description of a message’s content to the programs that understand their meaning.  Vendor-specific media types also have to be registered with the IANA.

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 affects 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
• Rule: Media type negotiation should be supported when multiple representations are available
• Rule: Media type selection using a query parameter may be supported

HTTP Headers and Metadata Design in RESTful APIs

Various forms of metadata may be conveyed through the entity headers contained within HTTP’s request and response messages. HTTP defines a set of standard headers, some of which provide information about a requested resource. Other headers indicate something about the representation carried by the message. Finally, a few headers serve as directives to control intermediary caches.

HTTP header fields are components of the header section of request and response messages in the Hypertext Transfer Protocol (HTTP). They define the operating parameters of an HTTP transaction.

There are some rules as to how the header should be structured. I have given a few below

1. The Content-Type header names the type of data found within a request or response message’s body. The value of this header is a specially formatted text string known as a media type,
2. The Content-Length header gives the size of the entity-body in bytes—-a client can know whether it has read the correct number of bytes from the connection. Second, a client can make a HEAD request to find out how large the entity-body is, without downloading it.
3. The Last-Modified header applies to response messages only. The value of this response header is a timestamp that indicates
4. The Location response header’s value is a URI that identifies a resource that may be of interest to the client.

Caching is one of the most useful features built on top of HTTP and it should be encouraged. You can take advantage of caching to reduce client-perceived latency, to increase reliability, and to reduce the load on an API’s servers. Caches can be anywhere. This is one of the cost effective constraints imposed and there are more than 5 rules are to encourage caching

• Cache-Control, Expires, and Date response headers should be used to encourage caching.
• Cache-Control, Expires, and Pragma response headers may be used to discourage caching.
• Expiration caching headers should be used with 200 (“OK”) responses.
• Expiration caching headers may optionally be used with 3xx and 4xx responses.

Interaction Design with HTTP

REST APIs embrace all aspects of the HyperText Transfer Protocol, including its request methods, response codes and message headers. HTTP defines methods (sometimes referred to as verbs) to indicate the desired action to be performed on the identified resource. What this resource represents, whether pre-existing data or data that is generated dynamically, depends on the implementation of the server. Often, the resource corresponds to a file or the output of an executable residing on the server.

• Clients specify the desired interaction method in the Request-Line part of an HTTP request message.

Request-Line = Method SP Request-URI SP HTTP Version CRLF

Each HTTP method has specific, well-defined semantics within the context of a REST API’s resource model. The purpose of GET is to retrieve a representation of a resource’s state. HEAD is used to retrieve the metadata associated with the resource’s state. PUT should be used to add a new resource to a store or update a resource. DELETE removes a resource from its parent. POST should be used to create a new resource within a collection and execute controllers.

These are some of the ground rules relating to HTTP Request Methods:

• Rule: GET and POST must not be used to tunnel other request methods
  • Tunneling refers to any abuse of HTTP that masks or misrepresents a message’s intent and undermines the protocol’s transparency. A REST API must not compromise its design by misusing HTTP’s request methods in an effort to accommodate clients with limited HTTP vocabulary.
• Rule: GET must be used to retrieve a representation of a resource
• Rule: HEAD should be used to retrieve response headers

REST APIs use the Status-Line part of an HTTP response message to inform clients of their request’s overall result.  HTTP defines forty standard status codes that can be used to convey the results of a client’s request. The status codes are divided into the five categories

1. 1xx: Informational – Communicates transfer protocol-level information.
2. 2xx: Success – Indicates that the client’s request was accepted successfully.
3. 3xx: Redirection – Indicates that the client must take some additional action in order to complete their request.
4. 4xx: Client Error – This category of error status codes points the finger at clients.
5. 5xx: Server Error – The server takes responsibility for these error status codes.

URI Query Design

A query string is the part of a uniform resource locator (URL) containing data that does not fit conveniently into a hierarchical path structure. The query string commonly includes fields added to a base URI by a Web browser or other client application, for example as part of an HTML form.

Following are the rules relating to the design of URI queries.

• Rule: The query component of a URI may be used to filter collections or stores

GET /users

GET /users?role=admin

• Rule: The query component of a URI should be used to paginate collection or store results

GET /users?pageSize=25&pageStartIndex=50

POST /users/search

Parameters: pageSize, pageStartIndex