Resources as nouns

Address resources with unique URLs.

In REST APIs, URIs point to resources, which are entities that can be accessed or manipulated. The action is represented by the HTTP method part of the request.

This means all URIs should be nouns rather than verbs.

Pros

Ensures API is robust against future requirements.

Guidelines

Rely on HTTP method semantics to communicate the action being performed on the resource

Actions

Method	Collection resource	Single object resource	Procedure resource
`GET`	List all records	Retrieve a record	N/A
`PUT`	N/A	Update (replace) a record	N/A
`POST`	Create a new record	Perform an action (update or other)	Execute the procedure
`PATCH`	N/A	Update a record	N/A
`DELETE`	N/A	Delete a record	N/A

For example, to create a User resource:

POST /users/create

You can rewrite it as:

POST /users

Similarly, deleting a user should use the DELETE method on the User resource:

DELETE /users/{user_id}

Avoid doing this:

POST /deleteUser

Transform action words into nouns

In English, most verbs have a corresponding noun form. For example, calculate becomes calculation, activate becomes activation, and so on.

If you're tempted to define a URI as a verb, you can often model it as an addressable resource using this tactic instead. For example, POST /customers/{customer}/verify would become POST /customers/{customer}/verifications.

You might wonder why this matters, since everything else about the endpoint remains the same. It is true that there is not much material difference between the two options yet. But the latter is much more scalable and can accomodate future business requirements much more readily.

A future requirement customer verification workflows may include the ability to view previous verification attempts and their status. If the verification process is a long running background job, the API may provide a way to cancel the process.

Use case	Endpoint
Verify a customer	`POST /customers/{customer}/verification`
List all verifications for a customer	`GET /customers/{customer}/verification`
Cancel a running verification	`POST /customers/{customer}/verification/{verification}/cancel`

You'll notice that the final endpoint ends with /cancel, not /cancellations, which contradicts this advice on this page. This is a judgement call for each API.

When describing the business at a high level, verifying a customer was discovered to be a complex process with its own lifecycle. While the initial version of the API only provided a way to initiate a verification, it was foreseen that there would be other jobs to be done in the future.

Whereas cancelling a verification was just that, without related jobs to be done. So is better represented as a state transition on a Customer Verification resource, rather than a operation on a distinct Customer Verification Cancellation resource.

Examples

OpenAPI definitions

Tips for well-structured OpenAPI definitions:

Ensure each operation has a summary and unique operationId.

Here is an example OpenAPI document:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Noun Resources Example API",
    "version": "1.0.0"
  },
  "tags": [
    {
      "name": "Customers"
    }
  ],
  "paths": {
    "/customers": {
      "tags": ["Customers"]
    },
    "/customers/{customer}": {
      "tags": ["Customers"]
    }
  }
}