IPA-101: Resource-Oriented Design

Resource-oriented design is a pattern for specifying APIs based on several 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
  • Custom methods are available in situations where the standard methods do not fit.
• Stateless protocol: Each interaction between the client and the server are independent, and both the client and server have clear roles

State

Adopt

Guidance

When designing an API, consider the following (roughly in logical order):

• 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 rely as much as possible on the standard verbs

Resources

• A resource-oriented API should generally be modeled as a resource hierarchy
  • Each node is either a simple resource or a collection of resources
  • A collection contains resources of the same type
  • A resource usually has fields
• Resources may have any number of sub-resources
• The schema for a resource must be the same across all methods related to the resource

Important

API producers should not expect that their API will be reflective of their database schema. Having an API that is identical to the underlying database schema is an antipattern, as it tightly couples the surface to the underlying system

Methods

A typical resource-oriented API exposes a large number of resources with a small number of methods on each resource and should not be confused with the HTTP methods. The methods here described related to the operations available on a resource.

The methods can be:

• The standard methods (Get, List, Create, Update, Delete)
• Custom methods

The following table illustrates the relationship between resources and the standard methods:

Standard method	Request	Response
Create	Contains the future resource	Is the resource
Get	None	Is the resource
Update	Contains the resource or parts of the resource	Is the current resource
Delete	None	None
List	None	Are the resources

• 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
  • Custom methods help define functionality that does not cleanly map to any of the standard methods

Readonly Resources

• Unsupported operations on readonly resources should return 405 Not Allowed
• Unsupported operations must not be documented
  • Some declarative-friendly clients require all standard methods to be implemented, but we consider documented unsupported methods to be in detriment of generated documentation and code