API Extensions

The following features may optionally be supported by implementations of the API.

Pagination

For large collections, the server may respond with only part of the collection in response to a GET collection request. If it does so, the server must provide URLs for other parts as part of the collection, using standard link relations in the top level of the response.

Example request:

curl -i http://example.org/annotations/

Example response:

HTTP/1.0 200 OK
Content-Type: application/ld+json

{
  "@context": ...
  "@id": "/annotations/",
  "generatedAt": "2012-04-09",
  "@graph":
  [
    ...
  ],
  "start": "/annotations",
  "next":  "/annotations?page=2"
  "last":  "/annotations?page=49402",
}

Content negotiation

All conformant implementations must support JSON-LD with the MIME type application/ld+json. RESTful Open Annotation stores may also support other formats through standard content negotiation. Namely, if the client specifies preference for one of the following in an Accept header, the store may respond with:

• text/html: human-readable representation
• application/rdf+xml: RDF/XML serialization
• application/n-triples: N-triples serialization (TODO: quads?)
• (TODO more)

(Conversion from JSON-LD to other RDF serializations is supported by the many libraries available e.g. from http://json-ld.org/)

Suggested extensions

The following extensions have been suggested but no specification has yet been provided.

• Annotations as sub-collection of document collection
• Search specification using URI templates
• HTTP PATCH support using JSON Patch
• Bulk update using POST and @graph instead of individual annotation
• Annotation collection deletion using DELETE for collection resource
• Allow annotations to be created on PUT (upsert)
• Optimistic concurrency control using ETags
• Minimal RESTful document store specification
• Structured error returns following e.g JSON API or Eve
• Representation of annotation confidence
• Representation of annotation license