A unique identifier is a value that distinguishes one entity or record from others. In an API, a resource identifier appears across operations and helps identify the resource being addressed. section 4.2.3 section 4.4.2
Represent resource identifiers as path parameters when they identify the operation’s resource. A collection such as /products becomes /products/{product reference}, making the path meaningful, hierarchical, and uniquely addressable. section 4.2.5 section 4.4.7
Product and banking paths
Use GET /products to search products and GET /products/123456 to read one product. If transaction IDs are globally unique, /transactions/{transactionId} can replace the longer customer-and-account path; retain parent identifiers when only their combination identifies the resource. section 4.9 section 9.3.3
Choose and place identifiers deliberately:
- Combine a resource name with its identifier when a bare value could be confused with another resource, such as /product-123456 rather than /123456. section 4.2.3
- Keep an identifier in the path when it identifies the resource; use a query parameter when it merely filters or modifies a broader collection. section 4.4.6 section 9.6.4
- Select identifier strategies per resource rather than enforcing one universal format; UUID enforcement is presented as a governance question requiring resource-specific judgment. section 16.12
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.
Visualizes the collection-plus-element pattern, showing how appending an element identifier creates a predictable child-resource path. section 4.2.5
