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:
| Parameters | Effect |
|---|---|
limit=5 | Return the first five items |
start=10&limit=5 | Returns the 10th to the 15th item ordered by id |
start-10&limit=5&order=slug | Returns the 10th to the 15th item ordered alphabetically by slug |
order=-created&limit=1 | Returns the most recently created item |
You can sort results by fields of related objects using the order parameter and a double underscore (__).
FOR EXAMPLE
| Parameters | Definition |
|---|---|
/api/episodes/?order=schedules__starts | Order Episodes by their schedule start date |
/api/sets/?order=set_type__slug | Order Sets by the slug of their Set Type |
/api/schedules/?order=affiliates__slug | Order 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
| Parameters | Definition |
|---|---|
/api/sets/?order_related_object_fields=image_urls__title | Order the images URLs on the set according to the title of the images |
/api/episodes/?order_related_object_fields=rating_urls__rating_position | Order the rating URLs according to the rating_position field |
/api/schedules/?order=affiliates__slug | Order Schedules by the slug of the Affiliate |
/api/brands/?order_related_object_fields=sponsor_urls__name | Order the Sponsor URLs according to the sponsors’ name field |
/api/episodes/?order_related_object_fields=talent__talent_url__last_name | Order the Talent according to their last_name |
/api/sets/?order_related_object_fields=tags__tag_url__name | Order 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.