Skip to content

Resource-oriented design

Resource-oriented design is a pattern for specifying RPC APIs, based on the following high-level design principles:

  • The fundamental building blocks of an API are individually-named resources (nouns) and the relationships and hierarchy that exist between them.
  • A small number of standard methods (verbs) provide the semantics for most common operations. However, custom methods are available in situations where the standard methods do not fit.

Readers might notice similarities between these principles and some principles of REST; resource-oriented design borrows many principles from REST, while also defining its own patterns where appropriate.

Guidance

When designing an API, consider the following:

  • The resources (nouns) the API will provide.
  • The relationships and hierarchies between those resources.
  • The schema of each resource.
  • The methods (verbs) each resource provides, relying as much as possible on the standard verbs.

Resources

A resource-oriented API must be modeled as a resource hierarchy, where each node is either a simple resource or a collection of resources.

A collection contains resources of the same type. For example, a publisher has the collection of books that it publishes. A resource usually has fields, and resources may have any number of sub-resources (usually collections).

Methods

Resource-oriented APIs emphasize resources (data model) over the methods performed on those resources (functionality). A typical resource-oriented API exposes a large number of resources with a small number of methods on each resource. The methods can be either the standard methods (Get, List, Create, Update, Delete), or custom methods.

If the request to or the response from a standard method (or a custom method in the same service) is the resource or contains the resource, the resource schema for that resource across all methods must be the same.

Standard methodRequestResponse
CreateContains the resourceIs the resource
GetNoneIs the resource
UpdateContains the resourceIs the resource
DeleteNoneNone
ListNoneIs the resource

The table above describes each standard method’s relationship to the resource, where “None” indicates that the resource neither is nor is contained in the request or the response

A resource must support at minimum Get: clients must be able to validate the state of resources after performing a mutation such as Create, Update, or Delete.

A resource must also support List, except for singleton resources where more than one resource is not possible.

APIs should prefer standard methods over custom methods; the purpose of custom methods is to define functionality that does not cleanly map to any of the standard methods. Custom methods offer the same design freedom as traditional RPC APIs, which can be used to implement common programming patterns, such as database transactions, import and export, or data analysis.

Strong Consistency

A method is strongly consistent if, upon completion of a request of that method (regardless of whether the request is successful, long-running or synchronous), all user-settable fields will return the same value on any subsequent requests until another request which mutates the resource is completed.

Output only fields unrelated to the resource state should also return the same value on each subsequent request until another request which mutates the resource is completed.

  • An output only field that takes so long to reach a steady-state that it would negatively impact the user experience of the request (e.g. an hour-long instantiation of a VM cluster).

Examples of strong consistency include:

  • Following a successful create that is is latest mutation on a resource, a get request for a resource must return the resource.
  • Following a successful update that is the latest mutation on a resource, a get request for a resource must return the final values from the update request.
  • Following a successful delete that is the latest mutation on a resource, a get request for a resource must return NOT_FOUND (or the resource with the DELETED state value in the case of soft delete)

Clients of resource-oriented APIs often need to orchestrate multiple operations in sequence (e.g., create resource A, create resource B which depends on A), and ensuring that resources immediately reflect steady user state after an operation is complete ensures clients can rely on method completion as a signal to begin the next operation.

Output only fields ideally would follow the same guidelines, but as these fields can often represent a resources live state, it’s sometimes necessary for these values to change after a successful mutation operation to reflect a state change.

Cyclic References

The relationship between resources, such as parent-child or resource references, must be representable via a directed acyclic graph.

A cyclic relationship between resources increases the complexity of managing resources. Consider resources A and B that refer to each other. The process to create said resources are:

  1. create resource A without a reference to B. Retrieve id for resource A.
  2. create resource B with a reference to A. Retrieve id for resource B.
  3. update resource A with the reference to B.

The delete operation may also become more complex, due to reasoning about which resource must be dereferenced first for a successful deletion.

This requirement does not apply to relationships that are expressed via output only fields, as they do not require the user to specify the values and in turn do not increase resource management complexity.

Changelog