Seek Item

This specification provides a way to seek the page of a collection that contains a particular item. It can also be used to test the membership of an item in a collection.

This is an experimental specification and is undergoing regular revisions.

Introduction

One way for ActivityPub API clients to efficiently use a reverse-chronological collection like the messages collection is to store a last-seen activity or object id.

To get the latest data, the client can get the latest page from the collection (first property), then follow the next properties of each page, until it finds a page with last-seen activity id in the items or orderedItems property. All the data that has been read is the "latest data". The client might show the latest items first, and then use scrolling to show earlier items.

One problem with this process is when the client state is dependent on previous state. So, the client has to cache all the data in the latest pages until it finds the last-seen item, and then apply all the new activities in order, forwards in time, in order to calculate the current state. This takes time and memory.

One way to improve this process is to have a feature for jumping directly to the page with the last-seen activity, without reading all the later pages. Then, if the collection is bidirectionally navigable (it has next and prev links on each page), the client can navigate forward in time, up to the current page.

Terms

This specification introduces one new term, seekItem.

Endpoint

The endpoint defined by the seekItem term is an HTTPS URL.

It MUST accept an additional item URL parameter, which is the full ActivityPub object id for the item to be sought. The client MUST correctly add the item parameter, taking into account existing parameters for the endpoint, if any.

On success, the Location header of the returned entity MUST be the id of an ActivityPub object. If the sought item is in a page of the collection, it MUST be the id of that ActivityPub CollectionPage or OrderedCollectionPage object. If the collection contains the item directly in its items or orderedItems property, the endpoint MUST return the Collection or OrderedCollection itself.

On success, the HTTP status code MUST be 307 Temporary Redirect or 308 Permanent Redirect. A temporary redirect SHOULD be used if the item could be part of a different page or collection in a future request. A permanent redirect SHOULD be used if the item will always be part of the same page of this collection.

On failure, the endpoint SHOULD return a Problem Details document with Content-Type set to application/problem+json.

If the item in the item parameter is not in the items or orderedItems list of any of the pages of the collection, nor the collection itself, the HTTP status code MUST be 404 Not Found.

The endpoint SHOULD support authentication methods commonly used with ActivityPub, including OAuth 2.0 and HTTP Signature.

If the authenticated user is not authorized to read the item in the item parameter, or the Collection or CollectionPage it is in, the HTTP status code MUST be 404 Not Found. This prevents leaking information about the membership of an item in a collection.