Core API

This page briefly summarizes the core RESTful Open Annoatation API.

The core API defines a single collection resource, annotations. This collection and the individual annotation resources it contains can be manipulated using standard HTTP methods as follows:

	Resource
Method	Item (e.g. http://example.org/annotations/123)	Collection (e.g. http://example.org/annotations/)
GET	Read single annotation	Read all annotations
PUT	Create or update annotation	N/A
POST	N/A	Create annotation
DELETE	Delete annotation	N/A

(TODO: consider defining PATCH)

Not all HTTP method / resource combinations are valid: for example, the API does not define DELETE for the entire collection of annotations. Services should respond to the combinations marked N/A with the 405 Method Not Allowed HTTP status.

The method / resource combinations are specified in detail below.

GET annotation

Retrieve representation of single annotation (oa:Annotation).

Response: 200 OK and annotation in JSON-LD.

On error: 404 Not Found if the annotation does not exist. 410 Gone may be returned for deleted resources.

Example:

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

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

{
  "@context": "http://www.w3.org/ns/oa.jsonld",
  "@type": "oa:Annotation",
  "@id": "/annotations/123",
  "target": "/documents/456.txt#char=42,48"
  "body": "Person",
}

(TODO: @context is OA, but keys are Web Annotation WG)

PUT annotation

Update single annotation, or create it if it does not exist.

Response: 200 OK and representation of the updated or created annotation in JSON-LD. Note that the store may modify the submitted representation, e.g. by filling in "@id" or "annotatedAt".

On error: TODO

Example:

curl -X POST -i -H 'Content-Type: application/json' -d '
{
  "@context": "http://www.w3.org/ns/oa.jsonld",
  "@type": "oa:Annotation",
  "target": "/documents/456.txt#char=42,48"
  "body": "Person",
}
' http://example.org/annotations/789

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

{
  "@context": "http://www.w3.org/ns/oa.jsonld",
  "@type": "oa:Annotation",
  "@id": "/annotations/789",
  "annotatedAt": "2015-03-03T19:16:32+09:00",
  "annotatedBy": "/users/smp",
  "target": "/documents/456.txt#char=42,48"
  "body": "Person",
}

DELETE annotation

Permanently remove single annotation.

Response: 204 No Content

On error: TODO

Example:

curl -X DELETE http://example.org/annotations/123

HTTP/1.0 204 No Content

GET collection

Retrieve representation of annotation collection and all annotations contained in the collection. The collection is represented as a named graph.

Response: 200 OK and collection and annotations in JSON-LD.

On error: TODO

Example:

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

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

{
  "@context": ...
  "@id": "/annotations/",
  "generatedAt": "2012-04-09",
  "@graph":
  [
    {
      "@id": "/annotations/123",
      "target": "/documents/456.txt#char=42,48"
      "body": "Person",
      ...
    },
    {
      "@id": "/annotations/789",
      "target": "/documents/456.txt#char=56,64"
      "body": "Organization",
      ...
    },
  ]
}

POST collection

TODO

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/)

(TODO PUT/POST w/Content-Type other than application/ld+json)