Quickstart

The RESTful Open Annotation API provides a simple way to share annotations online.

As the name suggests, the API is REST-style and based on Open Annotation. The API represents resources using JSON-LD, a standard extension of the JSON format.

Basic annotations are simple:

{
  "@id": "http://178.79.168.194/api/annotations/1",
  "target": "http://en.wikipedia.org/wiki/Text_annotation#History"
  "body": "Some history of text annotation",
}

This page shows how to get started using the API though a series of examples that you can run with the curl tool (or similar), or try out by clicking on links.

Contents

• Read operations
  • Get annotation
  • Get collection
• Write operations
  • Create annotation
  • Update annotation
  • Delete annotation
• Next steps

Read operations

The API defines two endpoints types: an individual annotation, and a collection of annotations. Both support reading in the usual way, using the HTTP GET method.

(HTTP GET is the method your browser normally uses to read resources such as web pages, and the URLs below work also in the browser.)

Get annotation

You can find an example annotation at http://178.79.168.194/api/annotations/1. Using, curl, you can get it with the following request:

curl -X GET http://178.79.168.194/api/annotations/1

Response:

{
  ...
  "@id": "http://178.79.168.194/api/annotations/1",
  "body": "Some history of text annotation",
  "target": "http://en.wikipedia.org/wiki/Text_annotation#History"
  ...
}

(Parts omitted for brevity.) These fields are:

• @id: the globally unique identifier of the annotation.
• body: the information that the target is annotated with, here a short text string.
• target: the thing that is annotated, here a fragment (#History) of a Wikipedia article.

Note that the values of @id and target are HTTP URIs that you can look up to get useful information.

Get collection

To get all annotations in a collection, simply issue a GET to the annotations/ API endpoint such as http://178.79.168.194/api/annotations/:

curl -X GET http://178.79.168.194/api/annotations/

Response:

{
  "@graph": [
    {
      "@id": "http://178.79.168.194/api/annotations/1",
      "target": "..."
      ...
    },
    {
      "@id": "http://178.79.168.194/api/annotations/2",
      "target": "..."
      ...
    },
    ...
  },
  "next": "http://178.79.168.194/api/api/annotations?page=2"
  "last": "http://178.79.168.194/api/api/annotations?page=489",
  ...
}

Some things to note here:

• The data of the annotations in the collection is included.
• The collection is large, so the response contains only part of it.
• Pagination links are included using standard link relations (next, last, etc.).

If you just need to read annotations, this is all you need to get started! You may want to have a look at next steps below for more detail, or read on for info on how to create, update and delete annotations.

Write operations

Write operations are also defined in the usual way: annotations are created with the POST method, updated with PUT, and deleted with DELETE.

Create annotation

You can create new annotations by POSTing JSON data to an annotations/ API endpoint. For example:

curl -X POST -H 'Content-Type: application/ld+json' -d '
{
  "@context": "http://178.79.168.194/ns/restoa.jsonld",
  "target": "http://en.wikipedia.org/wiki/Linked_data"
}
' http://178.79.168.194/api/annotations

Note the following:

• The format is JSON-LD, and its content type is application/ld+json.
• JSON-LD documents require a context document, here identified using @context.
• This annotation has no body. Only target is required.

The server will respond to the above request with

{
  ...
  "@id": "http://178.79.168.194/api/annotations/2",
  "@type": "oa:Annotation",
  "annotatedAt": "2015-03-01T16:27:56",
  "serializedAt": "2015-03-01T16:27:56",
  "target": "http://en.wikipedia.org/wiki/Linked_data",
}

(The @id will have a different number when you run this. Please substitute the actual @id value that you got when running the PUT and DELETE examples below.)

Note that the server echoes back the annotation, and has added a number of fields:

• The unique @id that can be used to access the annotation via the API.
• @type: the annotation type. OA annotations must be instances of oa:Annotation.
• Provenance information such as annotatedAt and serializedAt (in ISO 8601 format).

Note that not all servers add provenance information, and some may reject annotations that have no @type.

Update annotation

Previously created annotations can be updated with PUT.

Request:

curl -X PUT -H 'Content-Type: application/ld+json' -d '
{
  "@context": "http://178.79.168.194/ns/restoa.jsonld",
  "target": "http://en.wikipedia.org/wiki/Annotation"
}
' http://178.79.168.194/api/annotations/2

(If this fails, make sure the URL is for an annotation @id that you previously created – the number “2” above is just an example.)

Response:

{
  "@id": "http://178.79.168.194/api/annotations/2",
  "@type": "oa:Annotation",
  "target": "http://en.wikipedia.org/wiki/Annotation",
  "annotatedAt": "2015-03-01T16:27:56",
  "serializedAt": "2015-03-01T17:07:12",
  ...
}

The server has again filled in information missing from the request, also updating serializedAt to reflect the current time (last modification time).

Delete annotation

Annotations can be deleted with DELETE.

Request:

curl -i -X DELETE http://178.79.168.194/api/annotations/2

Response:

HTTP/1.1 204 NO CONTENT
...

A successful delete produces an empty response with the status code 204 NO CONTENT.

Next steps

For more detail on different parts of the API, you may wish to have a look at these pages:

• Data model: introduction to the abstract OA data model
• JSON-LD: information on the JSON-LD format
• Core API: technical specification of the core API
• Extensions: optional extensions to the core API

Also, the API is discoverable through use: as JSON-LD, all of its terms resolve to URLs that you can look up for more information.