A route parameter is a variable embedded in a resource path. Documentation denotes it with braces, such as /products/{productReference}; an HTTP request supplies a concrete value, such as /products/123456. Its main job is to identify the addressed resource, often by providing a unique identifier. section 4.2.1 section 4.2.3
Place an identifier in the path when it participates in resource identification. Keep nonhierarchical filters and other resource modifiers in query parameters; otherwise paths become mandatory, ambiguous, or difficult to understand. section 4.4.3 section 4.4.5
Use route parameters to express resource structure without making paths needlessly difficult to consume:
- Represent a collection as /products and one child as /products/{productReference}; concatenating the identifier makes the relationship clear. section 4.2.5
- Prefer meaningful paths over a bare identifier: /product-123456 communicates the resource type, while /123456 could conflict with another resource. section 4.2.3
- Shorten hierarchical paths when an identifier is globally unique; retain parent parameters when only their combination identifies the child. section 9.3.3
- Return 404 Not Found when a request using a route parameter targets a resource that does not exist. section 4.5.10
Library and product paths
A library API might use GET /books/12345/reviews?reviewId=678 to read a review, GET /books/borrowers/7890 to list a borrower’s books, and GET /books/12345 to retrieve a book. In a catalog API, use GET /products/{productReference} for one product and GET /products for the collection. The product reference identifies the product; reviewId and search filters modify or narrow returned data. section 4.11 section 4.2.5
OpenAPI declaration
Declare every route parameter in the path-level parameters list. The name must match the placeholder, its location must be path, and required must be true: paths: /products/{productReference}: parameters: - name: productReference in: path required: true schema: {} Define multiple parameters by adding more entries to the list. section 6.4.3
Treat path design as a consumer-facing contract. Avoid trailing slashes, preserve existing parameter options for compatibility, and add new options rather than removing or renaming accepted values. section 4.2.1 section 15.2.3
Figure 4.6 The “Product” resource path requires a unique resource identifier path parameter. Multiple segments can show the relationship between “Catalog” and “Product” resources.
Use the product-path diagram to compare bare identifiers, meaningful resource paths, and hierarchical catalog/product relationships. section 4.2.3
