3 Observing operations from the REST angle

This chapter moves from capability identification to designing a RESTful programming interface by first grounding the reader in HTTP and REST semantics and emphasizing interoperability through proper use of standardized methods and status codes. It distinguishes RESTful APIs from web APIs that merely use HTTP as transport while misusing its semantics, and it cautions that REST is a choice, not a default, even as it promotes user-friendly, standard-aligned designs. The chapter also stresses separating needs analysis from protocol decisions, keeping discussions in plain language with subject-matter experts to avoid bias and to maintain focus on what the API must achieve.

The practical core introduces a method for observing operations from the REST angle using the API Capabilities Canvas: reorganize information around operations, then identify resources (business concepts), their relations, and the actions applied to them. It offers techniques for spotting the right resource—using the main verb’s target, shortening or expanding descriptions, and recognizing nested or hierarchical resources—and patterns that simplify common CRUD cases: creation and listing target containers, while reading, updating, and deleting target individual elements. Relations typically emerge as “contains” or “belongs to,” and the chapter advises resisting influence from existing code or databases to keep designs faithful to the domain.

Actions are derived from each operation’s main verb, after which inputs and outputs are consolidated across steps in a context-agnostic way. Inputs usually exclude the operation’s resource unless multiple instances must be addressed; naming and identifiers are clarified with subject-matter experts and refined later during data modeling. Outputs merge success and error cases across contexts, with guidance to avoid heterogeneous payloads and to treat empty search results as a success for consistency and usability. Once resources, relations, actions, inputs, and outputs are clear, the next steps are to represent them with HTTP paths, methods, and status codes, and then design fine-grained data models, all under consistent guidelines that reinforce a coherent developer experience.

We design the REST programming interface based on the capabilities identified during the needs analysis. We focus on designing a versatile API that does the right job.

A browser or curl command loads a web page by sending an HTTP request containing a standard method and a path identifying the page. The server returns with an HTTP response confirming the page is found and its content.

How a client application calls a REST API is identical to when a web browser loads an HTML page.

Some web APIs don’t respect HTTP semantics. Their creator may wrongly call them "REST" simply because they leverage HTTP.

To efficiently and accurately design the programming interface representing the API capabilities, we observe the operations information of the API Capabilities Canvas from the REST angle, represent identified elements with HTTP, and finally model data.

This API Capabilities Canvas showcases the five typical API operations: searching for elements and creating, reading, updating, and deleting an element (CRUD).

Pivoting the API Capabilities Canvas to group information around operations simplifies our work. CRUD stands for Create, Read, Update, and Delete.

We expand the API Capabilities Canvas with the Operations and Ressources tables to keep track of our findings.

Using the operations information of the API Capabilities Canvas, we identify resources, their relations, and the actions that apply to them with their input and outputs.

We leverage description, input, success, and failure to identify the resource manipulated by an operation.

We can shorten the description to identify an operation’s resource.

We can expand the description to identify an operation’s resource.

We can leverage subject-matter knowledge and API Capabilities Canvas to identify resources relations.

We leverage the operation description’s main verb to Identify the action.

We can merge multiple context-specific step inputs into a unique and context-agnostic action input.

No merging is needed when a single step uses the operation, but we may improve descriptions.

We can uncover a new use case when including the operation resource in the inputs.

We merge the inputs of the different steps and exclude the operation resource from the action’s inputs.

We merge different steps' outcomes and rephrase descriptions when listing the action’s outputs.

No merge is necessary when a single step uses the operation.

We must turn consumer-context-specific steps' outcomes into context-agnostic operation/action outputs.

FAQ