GuidesAPI ReferenceDiscussions

Ordering

Suggest Edits

The Content API supports 3 main values for ordering.

All options can be in ascending or descending order by using asc and desc respectively.

Option 1 - First Created (Default)

This option simply orders items by the date & time they were first published.

Items can never bump back up a feed with this option.

https://content.api.pressassociation.io/v1/item?sort=firstcreated:desc

Option 2 - Issued (Recommended)

The issued option uses the following criteria to calculate the timestamp that an item should use for its order in a feed:

  • First Published - the date & time the item was first published.
  • Embargo expired - If the item was ever embargoed, this is the date & time of when that embargo expired.
  • Last corrected - If the item has ever been corrected, this is the date & time of when the last correction occured.

The most recent of these values is used for ordering.

This is a very useful ordering option as it allows important updates to items to bump items to the top of a feed, ensuring that you don't miss any vital changes to content. However it removes a lot of the noisy updates of the Version Created option.

https://content.api.pressassociation.io/v1/item?sort=issued:desc

🚧

With this option items can move position in a feed inbetween subsequent API calls. Users will need to handle this case in order to not encounter skipped or missing items when paginating through a list of API results.

Option 3 - Version Created

The version created option orders content by the last time an item was updated for any reason. This includes changes to metadata or attached media, as well as corrections to text content.

This can be useful for making sure you don't miss any changes to any items, however it can also be quite noisy and bump content to the top of a feed that really shouldn't be.

https://content.api.pressassociation.io/v1/item?sort=versioncreated:desc

Consistent Ordering

For the occassions where lots of stories are published at the same date & time (which can happen most nights at 00:01) users can add a second sort parameter to keep the order of items consistent between requests.

We suggest the uri field for this.

https://content.api.pressassociation.io/v1/item?sort=issued:desc&sort=uri:asc

Updated over 2 years ago