Mastering Resource‑Oriented API Design: Principles, Methods, and Stateless Protocols

Resource‑oriented design is a pattern for RPC APIs based on several high‑level design principles (most of which are common in public HTTP APIs):

API building blocks are named resources (nouns) together with their relationships and hierarchy.

A small set of standard methods (verbs) provides semantic common operations; custom methods are used when standard ones do not fit.

The protocol is stateless: each client‑server interaction is independent and roles are clearly defined.

Readers may notice that these principles borrow many ideas from REST, while also defining their own patterns where appropriate.

Guidelines

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

The resources (nouns) the API will expose.

The relationships and hierarchy among those resources.

The schema of each resource.

The methods (verbs) each resource provides, preferring standard verbs whenever possible.

Resources

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

A collection contains resources of the same type, e.g., a publisher’s collection of books. A resource typically has fields and may have any number of sub‑resources (often collections).

Note: Although there is conceptual overlap between storage systems and APIs, a resource‑oriented API does not have to be a database, and the API design should not be expected to mirror the underlying database schema. In fact, exposing the same schema as the database is an anti‑pattern because it tightly couples the surface to the underlying system.

Methods

Resource‑oriented APIs emphasize the data model rather than actions on it. Typical APIs expose many resources, each with a few methods. Standard methods include GET, LIST, CREATE, UPDATE, and DELETE; custom methods are also possible.

Note: Custom methods do not require new HTTP verbs; they use existing verbs (usually) and define the custom action in the URI, e.g., POST /resource/customAction .

APIs should prefer standard methods; custom methods are used only for functionality that cannot be cleanly mapped to a standard verb, offering the same design freedom as traditional RPC APIs for patterns such as transactions, import/export, or data analysis.

Stateless Protocol

Like most public APIs today, resource‑oriented APIs run over a stateless protocol: each request’s behavior is independent of other requests made by the caller.

In a stateless API, the server is responsible for persisting data that may be shared across multiple clients, while the client bears the sole responsibility for maintaining its own state.