Filtering¶
Plural endpoints (such as collections) support restricting the set of returned results by means of filters. Filters are predicates that can be expressed by query parameters. Elements of the plural endpoint (such as records) that do not match the predicates are omitted from the response.
Single value
/collection?field=value
Sub-objects
/collection?field.subfield=value
Minimum and maximum
Prefix field name with min_
or max_
:
/collection?min_field=4000
Note
The lower and upper bounds are inclusive (i.e equivalent to greater or equal).
Note
lt_
and gt_
can also be used to exclude the bound.
Multiple values
Prefix field with in_
and provide comma-separated values.
/collection?in_status=1,2,3
Exclude
Prefix field name with not_
:
/collection?not_field=0
Exclude multiple values
Prefix field name with exclude_
:
/collection?exclude_field=0,1
Note
Will return an error if a field is unknown.
Note
The ETag
and Last-Modified
response headers will always be the same as
the unfiltered collection.
One important use of this is when polling for changes.
Polling for changes¶
The _since
parameter is provided as an alias for gt_last_modified
.
/collection?_since=1437035923844
When filtering on last_modified
every deleted records will appear in the
list with a deleted
flag and a last_modified
value that corresponds
to the deletion event.
If the If-None-Match: "<timestamp>"
request header is provided as described in
the section about timestamps and if the
collection was not changed, a 304 Not Modified
response is returned.
Note
The _before
parameter is also available, and is an alias for
lt_last_modified
(strictly inferior).
Note
_since
and _before
also accept a value between quotes ("
) as
it would be returned in the ETag
response header
(see response timestamps).
Request:
GET /articles?_since=1437035923844 HTTP/1.1
Accept: application/json
Authorization: Basic bWF0Og==
Host: localhost:8000
Response:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length, ETag, Next-Page, Total-Records, Last-Modified
Content-Length: 436
Content-Type: application/json; charset=UTF-8
Date: Tue, 28 Apr 2015 12:08:11 GMT
Last-Modified: Mon, 12 Apr 2015 11:12:07 GMT
ETag: "1430222877724"
Total-Records: 2
{
"data": [
{
"id": "dc86afa9-a839-4ce1-ae02-3d538b75496f",
"last_modified": 1430222877724,
"title": "MoCo",
"url": "https://mozilla.com",
},
{
"id": "23160c47-27a5-41f6-9164-21d46141804d",
"last_modified": 1430140411480,
"title": "MoFo",
"url": "https://mozilla.org",
},
{
"id": "11130c47-37a5-41f6-9112-32d46141804f",
"deleted": true,
"last_modified": 1430140411480
}
]
}