Controlling Responses

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:

Specific value/api/episodes/?slug=titanicReturns the Episodes with the slug ‘titanic’
Not a specific value/api/episodes/?-slug=titanicReturns Episodes that don’t have the slug ‘titanic’
One of a list of valuesapi/episodes/?slug__in=titanic,groundhogday,primerReturns Episodes that have any one of the included slugs
String contains a substring/api/episodes/?slug__contains=festivalReturns episodes with slugs containing the specified string (case-sensitive)
String contains a substring/api/episodes/?slug__icontains=festivalReturns episodes with slugs containing the specified string (case-insensitive)
Specified timestamp/api/episodes/​?created__gte=2016-03-31T12:34:56Created at of after the given timestamp. Dates and times are specified in ISO8601 format
Relative timestamp/api/episodes​?created__gt=-10 dayCreated 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=trueReturn all Sets with a blank description
Null/api/sets/?sponsor__isnull=trueReturn 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-testReturns 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:

__gteGreater than or equal to the timestamp
__gtGreater than the timestamp
__lteLess than or equal to the timestamp
__ltLess than the timestamp

For more specific results, multiple filters can be chained together:


This example would return any Object with a slug ‘titanic’ that was published on or after the specified date


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=(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.


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.