A resource is a standalone business concept or entity that an API manipulates. It uses domain terminology, can exist independently, and differs from its properties: a Product is a resource, while its name is merely data belonging to it. A property such as price may become a resource when its history must be tracked. section 3.3.1
Identify a resource by examining an operation’s description, inputs, success, and failure. The main verb usually targets one resource, while several operations can manipulate that same resource. section 3.3.2
Use these practical identification patterns:
- For reading, updating, or deleting an element, treat the individual element as the resource. section 3.3.5
- For creating, adding, listing, or searching elements, treat their container as the resource. section 3.3.5
- Shorten an ambiguous operation description, or expand it with its context; “Add a product to a merchant’s catalog” identifies the merchant’s catalog. section 3.3.3
- Derive relations from domain knowledge and operation outcomes, such as “Catalog contains Product” and “Product belongs to Catalog.” section 3.3.4
From business operation to HTTP resource
“Search for products” manipulates a catalog containing products. Represent that resource as /products, use GET for the Search action, pass filters in the query, and return product information in the response body with 200 OK. section 4.1.2
Figure 3.3 How a client application calls a REST API is identical to when a web browser loads an HTML page.
Compare a REST API call with a browser request: both use an HTTP method and path, while the API returns structured business data. section 3.1.2
