A resource modifier changes an operation’s scope, filtering, or interpretation without identifying its primary resource. Typical modifiers include product type, description, category, keywords, and representation preferences. section 4.4.2 section 4.4.5
Place modifiers in query parameters because they alter returned data while leaving the business entity unchanged. Use a standard HTTP header instead when the modifier belongs to request metadata, such as an Accept preference. section 4.4.5 section 4.4.7
Filtering a product catalog
GET /products?type=book&description=design searches the Catalog with filters. The filters modify the returned products; they do not turn type or description into catalog path segments. A category reference can work similarly: use it as a query modifier when products remain searchable without it. section 4.4.5 section 4.4.6
Distinguish modifiers from resource identifiers before adding operations:
- Use a path parameter when the input participates in identifying the resource, such as /products/{productReference}. section 4.4.3
- Use a query parameter when the input only filters or otherwise tweaks returned data. section 4.4.5
- Test the operation without the input: if the resource can still be identified and searched, the input is likely a modifier. section 4.4.6
- Return to consumer needs and identified capabilities before creating specialized paths such as category- or supplier-based product operations. section 4.4.6
Figure 9.6 Using a path parameter for the account identifier and query parameters for the transaction resource modifiers makes the “Search account transactions” operation user-friendly.
The operation combines a path parameter for the account identifier with query parameters for transaction modifiers. section 9.4.1
