A resource path is the URI path that identifies a REST resource, such as a collection or one of its elements. In https://api.server.com/path, /path is the resource path. It must be unique for a resource, but different paths may lead to the same resource. Path segments are separated by slashes, and path parameters mark values supplied in requests, such as /products/{productReference}. section 4.2.1
Design paths around resources rather than operations. Use meaningful nouns, keep the hierarchy predictable, and let HTTP methods express actions. A catalog of products can use /products; an individual product can use /products/{productReference}. This makes the relationship clear and lets consumers construct an element path by appending its identifier. section 4.2.2 section 4.2.5 section 9.3.1
Searching and reading products
A mobile application can search the catalog with GET /products?type=BD. The path identifies the product collection, while type=BD is a query parameter that filters it. Reading one product uses GET /products/12345, where 12345 is a path parameter identifying the element. section 4.1.1 section 4.9
Use these design checks when choosing or reviewing a resource path:
- Prefer /catalog or /products over cryptic or abbreviated names such as /xyz or /cat. section 4.2.2
- Keep collection and element forms consistent: use /accounts and /accounts/{accountId}, not /accounts and /account/{accountId}. section 9.3.2
- Place parent-child relationships in the hierarchy, as in /accounts/{accountId}/transactions. section 9.3.2
- Shorten a path when a trailing resource identifier is globally unique; retain parent identifiers when they are needed for uniqueness. section 9.3.3
- Avoid trailing slashes because /path/ can cause routing problems. section 4.2.1
- Treat path changes as compatibility changes: modifying static segments or removing parameter options can produce 404 Not Found responses for consumers. section 15.2.3
In OpenAPI, declare each resource path as a key under paths. A parameterized path must define every path parameter with matching name, in: path, required: true, and a schema. Add a natural-language summary so consumers can understand the resource without decoding the URL. section 6.4.2 section 6.4.3
Figure 4.7 A list is represented by a noun that indicates its element type (usually plural, but can also be singular). The element identifier is added to the list path, forming the element path. This pattern is widely adopted in REST APIs.
The collection-to-element pattern shows how a noun identifies the list and an appended identifier identifies one child resource. section 4.2.5
