Searching and Filtering
Filtering limits the list of returned resources of an API endpoint by specific criteria.
APIs supporting filtering on resource collections MUST do so using one of the following methods:
- Service-specific query parameters
- Service-specific query payload
Filtering by Service-Specific Query Parameters
Section titled “Filtering by Service-Specific Query Parameters”APIs with simple filtering needs (limited to several status query parameters and without the need for free-text search, disjunction, or negation) MAY use dedicated query parameters specific to the service. All query parameters and their types MUST be documented in the API specification.
Example
GET /api/products?businessAreaNumber=203APIs requiring more complex queries than supported by ad-hoc query parameters, but not requiring a custom query payload in the body of a request, MAY implement RSQL for query consistency across services.
Filtering Using a Service-Specific Query Payload
Section titled “Filtering Using a Service-Specific Query Payload”Filtering scenarios not covered by query parameters will need to leverage a service-specific query contract submitted in the body of HTTP requests. APIs that implement a query mechanism specific to an API MUST describe and document that mechanism in the API documentation.
Example
POST /api/geofences/searches
{"fence":{"within":{"lat":"32+-1.0", "lon":"42.30+-0.5"}}}