Resource Modeling

A REST API's resource model is conveyed by its URI paths; with each forward-slash separated path element corresponding to a unique resource within the model's hierarchy.

For example, this URI design:

http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet

Indicates that each of these URIs should also identify an addressable resource:

http://api.soccer.restapi.org/leagues/seattle/teams, http://api.soccer.restapi.org/leagues/seattle, http://api.soccer.restapi.org/leagues, http://api.soccer.restapi.org

Resource modeling is an exercise that establishes a REST API's key concepts.

This process is similar to the data modeling for a relational database schema or the classical modeling of an object-oriented system. It also closely resembles designing a Web site's section/folder heirarchy.

Resource Archetypes

When modeling an API's resources, we can start with the some basic resource archetypes.

Like design patterns, the resource archetypes help us consistently communicate the structures and behaviors that are commonly found in our REST API designs.

A modern REST API is composed of four distinct resource archetypes:

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.

With its fundamental field and link-based structure, the document type is the conceptual base archetype of the other resource archetypes. In other words, the three other resource archetypes can be viewed as specializations of the document archetype.

Each URI below identifies a document resource.

http://api.soccer.restapi.org/leagues/seattle, http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet, http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/mike

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. A collection resource chooses what it wants to contain and also decides the URIs of each contained resource.

Each URI below identifies a collection resource.

http://api.soccer.restapi.org/leagues, http://api.soccer.restapi.org/leagues/seattle/teams, http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players

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.

The example interaction below shows a user (with ID 1234) of a client program using a fictional Soccer REST API to insert a document resource named alonso in his or her store of favorites.

PUT /users/1234/favorites/alonso

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 (CRUD).

Controller names typically appear as the last segment in a URI path, with no child resources to follow them in the hierarchy. The example below shows a controller resource that allows a client to resend an alert to a user.

POST /alerts/245743/resend

URI Path Modeling

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

The figure below exemplifies the correlation of a URI path's design with the resource model that it conveys.

WRML and HTTP/1.1

WRML Whiteboard Screens