Paging, Limiting & Ordering

The Skylark API also provides paging functionality.

Limiting and ordering parameters can be applied to most API endpoints using the URL parameters start, limit and order

By default all items returned are ordered by internal id. Sort order is ascending by default. It can be reversed by prefixing - (minus sign) for descending.

For example:

ParametersEffect
limit=5Return the first five items
start=10&limit=5Returns the 10th to the 15th item ordered by id
start-10&limit=5&order=slugReturns the 10th to the 15th item ordered alphabetically by slug
order=-created&limit=1Returns the most recently created item

You can sort results by fields of related objects using the order parameter and a double underscore (__).

FOR EXAMPLE

ParametersDefinition
/api/episodes/?order=schedules__startsOrder Episodes by their schedule start date
/api/sets/?order=set_type__slugOrder Sets by the slug of their Set Type
/api/schedules/?order=affiliates__slugOrder Schedules by the slug of the Affiliate

Where relationships are returned as a list of URLs, the list can be ordered using the order_related_object_fields parameter and the __ (double underscore) to browse objects and fields.

For an episode with several schedules related to it, we can sort the URLs of the schedules according to the schedules’ starts field when we provide the order_related_object_fields parameter:

/api/episodes/?order_related_object_fields=schedule_urls__starts

Other Examples

ParametersDefinition
/api/sets/?order_related_object_fields=image_urls__titleOrder the images URLs on the set according to the title of the images
/api/episodes/?order_related_object_fields=rating_urls__rating_positionOrder the rating URLs according to the rating_position field
/api/schedules/?order=affiliates__slugOrder Schedules by the slug of the Affiliate
/api/brands/?order_related_object_fields=sponsor_urls__nameOrder the Sponsor URLs according to the sponsors’ name field
/api/episodes/?order_related_object_fields=talent__talent_url__last_nameOrder the Talent according to their last_name
/api/sets/?order_related_object_fields=tags__tag_url__nameOrder the tags according to the name of the tag_url related objects

Specifying Returned Fields

On most endpoints, it is possible to select which fields the API returns by adding the fields parameter to the request URL. Set fields to a comma separated list of field names to return only the named fields in the API response.

/api/sets/?fields=uid,slug

Generally, Skylark will represent relationships between objects as a URL pointing at the related object.

If you set the parameter fields_to_expand to a comma separated list of field names, the URL they contain will be replaced by the full object you would get requesting these URLs.

/api/article/?fields_to_expand=author_url,attribute_url

Field limitation and field expansion can be used at the same time:

/api/article/?fields=author_url&fields_to_expand=author_url

You can limit fields in expanded fields by using two underscores. For example:

/api/article/?fields=author_url,author_url__uid&fields_to_expand=author_url

You can expand and limit fields inside other fields, by using two underscores:

/api/sets/coll_e8400ca3aebb4f70baf74a81aefd5a78/?fields_to_expand=items__content_url&fields=slug,items,items__content_url,items__content_url__slug

If a provided field does not match an object field, a 400 Bad Request error is returned showing which field is wrong.