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

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

URI Path Design

Each URI path segment, separated by forward slashes (/), represents a design opportunity. Assigning meaningful values to each path segment helps to clearly communicate the hierarchical structure of a REST API’s resource model design.

  • Rule: A singular noun should be used for document names

  • Rule: A plural noun should be used for collection names

  • Rule: A plural noun should be used for store names

  • Rule: A verb or verb phrase should be used for controller names

  • Rule: Variable path segments may be substituted with identity-based values. The URI template example below has three variables (leagueId,teamId, and playerId):{leagueId}/teams/{teamId}/players/{playerId}

Resource Modeling in REST APIs

The URI path conveys a REST API’s resource model, with each forward slash separated path segment corresponding to a unique resource within the model’s hierarchy. For example, this URI design:

This process is similar to the data modeling for a relational database schema or the classical modeling of an object-oriented system.

In order to communicate a clear and clean resource model to its clients, a REST API should align each resource with only one of these archetypes. Like design patterns, the resource archetypes help us consistently communicate the structures and behaviors that are commonly found in REST API designs. A REST API is composed of four distinct resource archetypes: document, collection, store, and controller. For uniformity’s sake, resist the temptation to design resources that are hybrids of more than one archetype. Instead, consider designing separate resources that are related hierarchically and/or through links.

  1. Document

A document resource is a singular concept that is akin to an object instance or database record. A document’s state representation typically includes both fields with values and links to other related resources

Each URI below identifies a document resource:
  1. Collection

A collection resource is a server-managed directory of resources. Clients may propose new resources to be added to a collection. However, it is up to the collection to choose to create a new resource, or not. Resources can be grouped into collections. Each collection is homogeneous so that it contains only one type of resource, and unordered. Resources can also exist outside any collection. In this case, we refer to these resources as singleton resources. Collections are themselves resources as well.

Each URI below identifies a collection resource:
  1. Store

A store is a client-managed resource repository. A store resource lets an API client put resources in, get them back out, and decide when to delete them. On their own, stores do not create new resources; therefore a store never generates new URIs. Instead, each stored resource has a URI that was chosen by a client when it was initially put into the store.

To insert a document resource named alonso in his or her store of favorites:

PUT /users/1234/favorites/alonso
  1. Controller

A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs. Like a traditional web application’s use of HTML forms, a REST API relies on controller resources to perform application-specific actions that cannot be logically mapped to one of the standard methods (Create, Retrieve, Update, and Delete, also known as


POST /alerts/245743/resend

Controller names typically appear as the last segment in a URI path