Skylark allows responses returned to be both reduced or expanded so that constructing a view in a client application can be done with a minimal number of API calls and with the minimum required data transferred. The API also provides paging functionality.
Use Cases
- Remove unneeded fields from a response to save on data transfer
- Expand relationships to minimise API calls
- Provide paged search results
- Returning only matching results
Filtering By Schedule
Lists are filtered by schedule according to the request context. This is explained in more detail in the Scheduling section.
Filtering Objects Using Field Values
Skylark API can return results using queries on fields and values. This allows client applications to get specific search results. These filters can also be used to automatically generate Set contents using Computed Scheduled Items.
The Skylark API can filter in several different ways:
| Filter | Example | Result |
|---|---|---|
| Specific value | /api/episodes/?slug=titanic | Returns the Episodes with the slug ‘titanic’ |
| Not a specific value | /api/episodes/?-slug=titanic | Returns Episodes that don’t have the slug ‘titanic’ |
| One of a list of values | api/episodes/?slug__in=titanic,groundhogday,primer | Returns Episodes that have any one of the included slugs |
| String contains a substring | /api/episodes/?slug__contains=festival | Returns episodes with slugs containing the specified string (case-sensitive) |
| String contains a substring | /api/episodes/?slug__icontains=festival | Returns episodes with slugs containing the specified string (case-insensitive) |
| Specified timestamp | /api/episodes/?created__gte=2016-03-31T12:34:56 | Created at of after the given timestamp. Dates and times are specified in ISO8601 format |
| Relative timestamp | /api/episodes?created__gt=-10 day | Created within the last 10 days. Relative dates are calculated with respect to the current time. |
| Relationships | /api/images/?image_type_url=/api/image-types/imag_97107d1bcf0b4d88914450b4524bf111/ | Images with the image_type_url field equal to the type at the given URL |
| Blank | /api/sets/?description__blank=true | Return all Sets with a blank description |
| Null | /api/sets/?sponsor__isnull=true | Return all Sets without a sponsor |
| Set Contents | /api/episodes/?in_sets= /api/sets/coll_e8400ca3aebb4f70baf74a81aefd5a78/,/api/sets/coll_88f0f403b71249eb9f255f7df15e14ed/ | Episodes that have been scheduled into either of the given Sets |
| Field on relationship | /api/episodes/?ratings__slug=rating-test | Returns Episodes with the given rating slug. |
| Multiple relationship URLs | /api/episodes/?tags____tag_url= /api/tags/tag____61799528abc7463abf8147bde3ddb8d3/,/api/tags/tag__3628192ece49448586eb4a5251153f6a/ | Returns Episodes that have either of the given tag URLs. |
Timestamp queries can use the following field suffixes:
| Suffix | Definition |
|---|---|
__gte | Greater than or equal to the timestamp |
__gt | Greater than the timestamp |
__lte | Less than or equal to the timestamp |
__lt | Less than the timestamp |
For more specific results, multiple filters can be chained together:
/?slug=titanic&publish_on__gte=
This example would return any Object with a slug ‘titanic’ that was published on or after the specified date
Errors
If any filter field does not match the Object queried, a 400 Bad Request error is returned showing which field can not be found.
Free Text Search
As well as structured filtering, many Skylark objects also support filtering using free-text search by adding the lucene_query parameter to the request containing a search query in Lucene syntax. The fields covered by the search index are dependent on the Skylark configuration.
/?lucene_query=titanic
/?lucene_query=(title:titanic OR synopsis:titanic)
If the complexity of a lucene query is not required, comma-separated search terms can be used with the query parameter e.g.
/?query=title:foo,genre:bar`
If a field does not exist or is not indexed this will just return an empty result list. The fields covered by this feature are dependent on the Skylark configuration.
Free text search can be combined with other filters, though care needs to be taken with performance. End-user facing search features should prefer the Multi-search API, which can search over multiple resource types, track popular searches, and provide spelling corrections.