Plural vs singluar resources

Apply predictable spelling conventions to URLs.

A common debate amongst REST API designers is whether to name patch segments in URLs as the plural or singular spelling of the resource.

Collection and object resources - describe relationship between collection and object

/customers
/customers/{customer_id}

The counter argument is that having a plural word in the URI of the object resource is contradictory, so sometimes API designers create URI structures like this:

/customers
/customer/{customer_id}

Here the collection containing mutiple customers is plural, and the single customer resource URI is singular. The porblem with this is that the presence of /customer/{customer_id} implies the existence of a /customer resource too, which is meaningless and would return a 404 Not Found responds.

The former approach is preferred because there it reflects the natural heirarchy between a collection its objects in the path. This is consistent with how filesystems and other directory structures use URIs.

if the collection resource contains other nested resources that aren't the collection's objects, take care that the nested resource name does not collide with a possible object identifier.

For example, a Customers Search resource may have the URI:

/customers/search

If your API allows any string to be used as an identifier, then on the off-change a customer's ID is search. This is incredibly unlikely in practice, but possbile if IDs can be defined by the client.

This is easilty mitigated by generating identities on the server and ensuring they are random strings, such as GUIDs.

Pros

Uses heirarcy part of URI (path) for intended purpose
communictes telatipnshoip between collection and oits objects
Does not imply existence of non-existent uris

Cons

object resources contain a plural spelling.
Nested resoruces that aren't hte collection's objects may collide with object ids.

Guidelines

Use plural spellings for collection and object URIs

Use singular spelleings for singleton objects URIs

Generate all identifiers on the server randomly

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": "Plural Resources Example API",
    "version": "1.0.0"
  },
  "tags": [
    {
      "name": "Customers"
    }
  ],
  "paths": {
    "/customers": {
      "tags": ["Customers"]
    },
    "/customers/{customer}": {
      "tags": ["Customers"]
    }
  }
}