Page MenuHomePhabricator

Decide on pagination and links spec for Core REST API
Open, Needs TriagePublic

Description

The parent task proposes to include properties in the API response with links to next/previous page. Given that pagination is a very standard thing to do and will be needed elsewhere, we need to either come up with a standard way of embedding links to related resources and pagination, or (even better) use an existing standard.

http://samplacette.com/five-json-rest-api-link-formats-compared/ gives a fairly solid overview of the solutions and draft RFCs that exist out there.

Related Objects

Event Timeline

@Pchelolo I'm open to having this conversation but not to having it block shipping the history endpoint.

Are you OK with keeping "older"/"newer" in the definition for the release, and we can talk about a generic paging mechanism for the future? We're using a semantic versioning strategy, so the history endpoint will keep these properties in backwards-compatible future versions, but we can add other paging properties at a minor cost.

Sound good?

I'm open to having this conversation but not to having it block shipping the history endpoint.

That's why I've opened a separate ticket. I will be expanding in this here

I've seen using the link relations names as properties in JSON, which I think is what we did with Activity Streams 2.0 collections. So:

  • "first" : first segment in the collection
  • "next": link to next segment in the collection
  • "prev": link to previous segment in the collection
  • "last": link to last segment in the collection

As I mentioned to Petr, for collections sorted in reverse chronological order, this can be confusing for users. The "first" segment will include the last-added items, and the "last" page will include the oldest items, including the first item. The "next" link shows you items that were created previously, and the "prev" link shows you items that were created next after those. People mess this up all the time.