Filtering, sorting, field selection and paging
Filtering
Use a unique query parameter for all fields or a query language for filtering.
GET /cars?color=red Returns a list of red cars
GET /cars?type=%2Avan%2A Returns a list of cars whose type contains the 'van' word (Minivan, Cargo Van...). %2A is the encoded form of the * wildcard.
GET /cars?seats<=2 Returns a list of cars with a maximum of 2 seast
Time selection
start_time or {property_name}_from, end_time or {property_name}_to query parameters should be provided if time selection is needed.
Sorting
Allow ascending and descending sorting over multiple fields.
GET /cars?sort=-manufactorer,+model
This returns a list of cars sorted by descending manufacturers and ascending models.
The sort order for each sort field MUST be specified with one of the following prefixes:
- Plus (U+002B PLUS SIGN, “+”) to request an ascending sort order.
- Minus (U+002D HYPHEN-MINUS, “-“) to request a descending sort order.
Field selection
Mobile clients display just a few attributes in a list. They don’t need all attributes of a resource. Give the API consumer the ability to choose returned fields. This will also reduce the network traffic and speed up the usage of the API.
GET /cars?fields=manufacturer,model,id,color
Nevertheless, you may choose that some fields would always be sent along with the requested fields, in the response payload. Like the id for example.
If one of the fields requested does not exist, a 400 Bad Request should be returned.
As explained in the Authorization chapter, in case the field requested should not be accessible to the calling user, a 403 Forbidden should be returned.
Paging
There are two popular ways how to support paging.
limit and offset style
Use limit and offset. It is flexible for the user and common in API implementations (Facebook). The default should be limit=20 and offset=0.
GET /products?limit=25&offset=50
Response Fields
{
"limit": 25,
"offset": 50,
"total_count": 1634
}
| Name | Type | Description |
|---|---|---|
| offset | Integer | The offset used in the execution of the query. |
| limit | Integer | The limit used in the execution of the query. |
| total_count | Integer | The total number of records available. |
Page style
Pages of results should be referred to consistently by the query parameters page and page_size, where page_size refers to the amount of results per request, and page refers to the requested page. Additionally, responses should include total_count and total_pages whenever possible, where total_count indicates the total records in the requested collection, and total_pages is the number of pages (interpolated from total_count/page_size).
The default should be page=1 and page_size=20.
GET /products?page=2&page_size=30
Response Fields
{
"page": 2,
"page_size": 30,
"total_count": 1634,
"total_pages": 55
}
| Name | Type | Description |
|---|---|---|
| page | Integer | The page used in the execution of the query. |
| page_size | Integer | The page_size used in the execution of the query. |
| total_count | Integer | The total number of records available. |
| total_pages | Integer | The total number of pages available |
Hypermedia links
Hypermedia links are high value in navigating paged resource collections, as page/page_size query parameters can be maintained while navigating pages of results.
Links should be provided with rels of next, previous, first, last wherever appropriate.