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
• A standard query language (FIQL)
• Service-specific query payload

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=203

Filtering using a Standard Query Language

For queries requiring comparisons, disjunctions (e.g., “A or B”), or negations, services MUST use the reserved q query parameter, whose value must be a FIQL query string. Parsers for FIQL are available in most mainstream languages.

Example:

GET /api/customers?q=last_name==foo*,(age=lt=55;age=gt=5)

Filtering Using a Service-Specific Query Payload

Filtering scenarios not covered by either of the above options 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. Please contact api-standard-ug@trimble.com if you implement this as the implementation could help determine the eventual Trimble standard.

Example:

POST /api/geofences/searches {"fence":{"within":{"lat":"32+-1.0", "lon":"42.30+-0.5"}}