4.1 Container Retrieval

The Annotation Server MUST support the following HTTP methods on the Annotation Container's IRI:

• GET (retrieve the description of the Container and the list of its contents, described below),
• HEAD (retrieve the headers of the Container without an entity-body),
• OPTIONS (enable CORS pre-flight requests [cors]).

When an HTTP GET request is issued against the Annotation Container, the server MUST return a description of the container. That description MUST be available in JSON-LD, SHOULD be available in Turtle, and MAY be available in other formats. The JSON-LD serialization of the Container's description SHOULD use both the LDP context (http://www.w3c.org/ns/ldp.jsonld), and the Web Annotation's profile and context [annotation-model], unless the request would determine otherwise.

Servers SHOULD use the 200 HTTP status code if the request is successfully completed without errors and does not require redirection based on the client's preferences.

All supported methods for interacting with the Annotation Container SHOULD be advertised in the Allow header of the GET, HEAD and OPTIONS responses from the container's IRI . The Allow header MAY also be included on any other responses.

Annotation Containers MUST return a Link header [rfc5988] on all responses with the following components:

• It MUST advertise its type by including a link where the rel parameter value is type and the target IRI is the appropriate Container Type, such as http://www.w3.org/ns/ldp#BasicContainer for Basic Containers.
• It MUST advertise that it imposes Annotation protocol specific constraints by including a link where the target IRI is http://www.w3.org/TR/annotation-protocol/, and the rel parameter value is the IRI http://www.w3.org/ns/ldp#constrainedBy.

All HTTP responses from Annotation Containers MUST include an ETag header that implements the notion of entity tags from HTTP [rfc7230]. This value will be used by administrative clients when updating the container by including it in an If-Match request header in the same way as clients wanting to update an Annotation.

If the Accept header is absent from the request, then Annotation Servers MUST respond with a JSON-LD representation of the Annotation Container, however clients with a preference for JSON-LD SHOULD explicitly request it using an Accept request header.

If the server supports content negotiation by format or JSON-LD profile, the response from the Annotation Container MUST have a Vary header that includes Accept in the value to ensure that caches can determine that the representation will change based on the value of this header in requests.

Responses from Annotation Containers that support the use of the POST method to create Annotations SHOULD include an Accept-Post header on responses to GET, HEAD and OPTIONS requests. The value is a comma separated list of media-types that are acceptable for the client to send via POST [ldp].

Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type"
Link: <http://www.w3.org/TR/annotation-protocol/>; rel="http://www.w3.org/ns/ldp#constrainedBy"
ETag: "0f6b5cd8dc1f754a1738a53b1da34f6b"
Vary: Accept
Allow: POST, GET, OPTIONS, HEAD
Accept-Post: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld", text/turtle

4.2 Container Representations

As there are likely to be many Annotations in a single Container, the Annotation Protocol adopts the ActivityStreams paging mechanism for returning the contents of the Container. Each page contains an ordered list with a subset of the managed Annotations, such that if every page is traversed, a client can reconstruct the complete, ordered contents of the container. The number of IRIs or Annotation descriptions included on each page is at the server's discretion, and may be inconsistent between pages. The feature or features by which the Annotations are sorted are not explicit in the response.

If there are greater than zero Annotations in the Container, the representation MUST either include a link to the first page of Annotations as the value of the first property, or include the representation of the first page embedded within the response. If there is more than one page of Annotations, then the representation SHOULD have a link to the last page using the last property.

The representation of the Container SHOULD include the total property with the total number of annotations in the Container.

The IRI of the Container provided in the response SHOULD differentiate between whether the pages contain just the IRIs, or the full descriptions of the Annotations. It is RECOMMENDED that this be done with a query parameter. The server MAY redirect the client to this IRI and deliver the response there, otherwise it MUST include a Content-Location header with the IRI as its value.

GET /annotations/ HTTP/1.1
Host: example.org
Accept: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Prefer: return=representation;include="http://www.w3.org/ns/ldp#PreferMinimalContainer http://www.w3.org/ns/oa#PreferContainedIRIs"

HTTP/1.1 200 OK
Content-Type: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
ETag: "_87e52ce123123"
Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type"
Link: <http://www.w3.org/TR/annotation-protocol/>; rel="http://www.w3.org/ns/ldp#constrainedBy"
Allow: POST,GET,OPTIONS,HEAD
Vary: Accept
Content-Length: 368

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://www.w3.org/ns/ldp.jsonld"
  ],
  "id": "http://example.org/annotations/?iris=1",
  "type": ["BasicContainer", "AnnotationCollection"],
  "total": 42023,
  "label": "A Container for Web Annotations",
  "first": "http://example.org/annotations/?iris=1&page=0",
  "last": "http://example.org/annotations/?iris=1&page=42"
}

GET /annotations/ HTTP/1.1
Host: example.org
Accept: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Prefer: return=representation;include="http://www.w3.org/ns/oa#PreferContainedIRIs"

HTTP/1.1 200 OK
Content-Type: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Content-Location: http://example.org/annotations/?iris=1
ETag: "_87e52ce123123"
Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type"
Link: <http://www.w3.org/TR/annotation-protocol/>; rel="http://www.w3.org/ns/ldp#constrainedBy"
Allow: POST,GET,OPTIONS,HEAD
Vary: Accept, Prefer
Content-Length: 397

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://www.w3.org/ns/ldp.jsonld"
  ],
  "id": "http://example.org/annotations/?iris=1",
  "type": ["BasicContainer", "AnnotationCollection"],
  "total": 42023,
  "label": "A Container for Web Annotations",
  "first": {
    "id": "http://example.org/annotations/?iris=1&page=0",
    "type": "AnnotationPage",
    "next": "http://example.org/annotations/?iris=1&page=1",
    "items": [
      "http://example.org/annotations/anno1",
      "http://example.org/annotations/anno2",
      "http://example.org/annotations/anno3",
      "http://example.org/annotations/anno4",
      "http://example.org/annotations/anno5",
      "http://example.org/annotations/anno6",
      ...
      "http://example.org/annotations/anno999",
    ]
  },
  "last": "http://example.org/annotations/?iris=1&page=42"
}

GET /annotations/ HTTP/1.1
Host: example.org
Accept: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Prefer: return=representation;include="http://www.w3.org/ns/oa#PreferContainedDescriptions"

HTTP/1.1 200 OK
Content-Type: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Allow: GET,OPTIONS,HEAD
Vary: Accept, Prefer
Content-Length: 924

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://www.w3.org/ns/ldp.jsonld"
  ],
  "id": "http://example.org/annotations/?iris=0",
  "type": ["BasicContainer", "AnnotationCollection"],
  "total": 42023,
  "label": "A Container for Web Annotations",
  "first": {
    "id": "http://example.org/annotations/?iris=0&page=0",
    "type": "AnnotationPage",
    "next": "http://example.org/annotations/?iris=0&page=1",
    "items": [
      {
        "id": "http://example.org/annotations/anno1",
        "type": "Annotation",
        "body": "http://example.net/body1",
        "target": "http://example.com/page1"
      },
      {
        "id": "http://example.org/annotations/anno2",
        "type": "Annotation",
        "body": {
          "type": "TextualBody",
          "value": "I like this!"
        },
        "target": "http://example.com/book1"
      }
      // ...
      {
        "id": "http://example.org/annotations/anno50",
        "type": "Annotation",
        "body" : "http://example.org/texts/description1",
        "target": "http://example.com/images/image1"
      }
    ]
  },
  "last": "http://example.org/annotations/?iris=0&page=840"
}

4.3 Annotation Pages

Individual pages are instances of CollectionPage. The page contains the Annotations, either via their IRIs or full descriptions, in the items property.

Each page MUST have a link to the container that it is part of, using the partOf property. If it is not the first page, it MUST have a link to the previous page in the sequence, using the prev property. If it is not the last page, it MUST have a link to the next page in the sequence, using the next property. The response MAY include properties of the Collection in the response, including the total number of items or first and last page links.

The client SHOULD NOT send the Prefer header when requesting the page, as it has already been taken into account when requesting the Container.

This specification does not require any particular functionality when a client makes requests other than GET, HEAD or OPTIONS to a page.

As the CollectionPage is not a Container, it does not have the requirement to include a Link header with a type. That the URLs can be constructed with query parameters added to the Container's IRI is an implementation convenience, and does not imply the type of the resource.

GET /annotations/?iris=1&page=0 HTTP/1.1
Host: example.org
Accept: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"

HTTP/1.1 200 OK
Content-Type: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Allow: GET,OPTIONS,HEAD
Vary: Accept, Prefer
Content-Length: 630

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/annotations/?iris=1&page=0",
  "type": "AnnotationPage",
  "partOf": {
    "id": "http://example.org/annotations/?iris=1",
    "total": 42023
  },
  "next": "http://example.org/annotations/?iris=1&page=1",
  "items": [
    "http://example.org/annotations/anno1",
    "http://example.org/annotations/anno2",
    "http://example.org/annotations/anno3",
    "http://example.org/annotations/anno4",
    "http://example.org/annotations/anno5",
    "http://example.org/annotations/anno6",
    ...
    "http://example.org/annotations/anno999",
  ]
}

GET /annotations/?iris=0&page=0 HTTP/1.1
Host: example.org
Accept: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"

HTTP/1.1 200 OK
Content-Type: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Allow: GET,OPTIONS,HEAD
Vary: Accept, Prefer
Content-Length: 924

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/annotations/?iris=0&page=0",
  "type": "AnnotationPage",
  "partOf": {
    "id": "http://example.org/annotations/?iris=0",
    "total": 42023
  },
  "next": "http://example.org/annotations/?iris=0&page=1",
  "items": [
    {
      "id": "http://example.org/annotations/anno1",
      "type": "Annotation",
      "body": "http://example.net/body1",
      "target": "http://example.com/page1"
    },
    {
      "id": "http://example.org/annotations/anno2",
      "type": "Annotation",
      "body": {
        "type": "TextualBody",
        "value": "I like this!"
      },
      "target": "http://example.com/book1"
    }
    // ...
    {
      "id": "http://example.org/annotations/anno50",
      "type": "Annotation",
      "body" : "http://example.org/texts/description1",
      "target": "http://example.com/images/image1"
    }
  ]
}

4.4 Discovery of Annotation Containers

As the IRI for Annotation Containers MAY be any IRI, and it is unlikely that every Web Server will support the functionality, it is important to be able to discover the availability of these services.

Any resource MAY link to an Annotation Container when Annotations on the resource SHOULD be created within the referenced Container. This link is carried in an HTTP Link header and the value of the rel parameter MUST be http://www.w3.org/ns/oa#annotationService.

For HTML representations of resources, the equivalent link tag in the header of the document MAY also be used.

GET /images/logo.jpg HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: image/jpeg
Link: <http://example.org/annotations/>; rel="http://www.w3.org/ns/oa#annotationService"
Allow: GET
Content-Length: 76983

[...]

5.1 Create a New Annotation

New Annotations are created via a POST request to an Annotation Container. The Annotation, serialized as JSON-LD, is sent in the body of the request. All of the known information about the Annotation SHOULD be sent, and if there are already IRIs associated with the resources, they SHOULD be included. The serialization SHOULD use the Web Annotation JSON-LD profile, and servers MAY reject other contexts even if they would otherwise produce the same model. The server MAY reject content that is not considered an Annotation according to the Web Annotation specification [annotation-model].

Upon receipt of an Annotation, the server MAY assign IRIs to any resource or blank node in the Annotation, and MUST assign an IRI to the Annotation resource in the id property, even if it already has one provided. The server SHOULD use HTTPS IRIs when those resources are able to be retrieved individually. The IRI for the Annotation MUST be the IRI of the Container with an additional component added to the end.

The server MAY add information to the Annotation. Possible additional information includes the agent that created it, the time of the Annotation's creation, or additional types and formats of the constituent resources.

If the Annotation contains a canonical link, then it MUST be maintained without change. If the Annotation has an IRI in the id property, then it SHOULD be copied to the via property, and the IRI assigned by the server, at which the Annotation will be available, MUST be put in the id field to replace it.

The server MUST respond with a 201 Created response if the creation is successful, and an appropriate error code otherwise. The response MUST have a Location header with the Annotation's new IRI.

POST /annotations/ HTTP/1.1
Host: example.org
Accept: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Content-Type: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Content-Length: 202

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "type": "Annotation",
  "body": {
    "type": "TextualBody",
    "value": "I like this page!"
  },
  "target": "http://www.example.com/index.html"
}

HTTP/1.1 201 CREATED
Allow: PUT,GET,OPTIONS,HEAD,DELETE,PATCH
Location: http://example.org/annotations/anno1
Content-Type: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Content-Length: 287
ETag: "_87e52ce126126"

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/annotations/anno1",
  "type": "Annotation",
  "created": "2015-01-31T12:03:45Z",
  "body": {
    "type": "TextualBody",
    "value": "I like this page!"
  },
  "target": "http://www.example.com/index.html"
}

5.2 Suggesting an IRI for an Annotation

The IRI path segment that is appended to the Container IRI for a resource MAY be suggested by the Annotation Client by using the Slug HTTP header on the request when the resource is created. The server SHOULD use this name, so long as it does not already identify an existing resource, but MAY ignore it and use an automatically assigned name.

POST /annotations/ HTTP/1.1
Host: example.org
Accept: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Content-Type: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Content-Length: 202
Slug: "my_first_annotation"

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "type": "Annotation",
  "body": {
    "type": "TextualBody",
    "value": "I like this page!"
  },
  "target": "http://www.example.com/index.html"
}

HTTP/1.1 201 CREATED
Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type"
Allow: PUT,GET,OPTIONS,HEAD,DELETE,PATCH
Location: http://example.org/annotations/my_first_annotation
Content-Type: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
ETag: "_87e52ce126126"
Vary: Accept
Content-Length: 301

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/annotations/my_first_annotation",
  "type": "Annotation",
  "created": "2015-01-31T12:03:45Z",
  "body": {
    "type": "TextualBody",
    "value": "I like this page!"
  },
  "target": "http://www.example.com/index.html"
}

5.3 Update an Existing Annotation

Annotations can be updated by using a PUT request to replace the entire state of the Annotation. Annotation Servers SHOULD support this method. Servers MAY also support using a PATCH request to update only the aspects of the Annotation that have changed, but that functionality is not specified in this document.

Replacing the Annotation with a new state MUST be done with the PUT method, where the body of the request is the intended new state of the Annotation. The client SHOULD use the If-Match header with a value of the ETag it received from the server before the editing process began, to avoid collisions of multiple users modifying the same Annotation at the same time.

Servers SHOULD reject update requests that modify the values of the canonical or via properties, if they have been already set.

If successful, the server MUST return a 200 OK status with the Annotation as the body according to the content-type requested. As with creation, the server MUST return the new state of the Annotation in the response.

PUT /annotations/anno1 HTTP/1.1
Host: example.org
Accept: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Content-Type: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Content-Length: 294
If-Match: "_87e52ce126126"

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/annotations/anno1",
  "type": "Annotation",
  "created": "2015-02-01T10:13:40Z",
  "body": {
    "type": "TextualBody",
    "value": "I REALLY like this page!"
  },
  "target": "http://www.example.com/index.html"
}

HTTP/1.1 200 OK
Content-Type: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
ETag: "_87e52ce234234"
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Allow: PUT,GET,OPTIONS,HEAD,DELETE,PATCH
Vary: Accept
Content-Length: 331

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/annotations/anno1",
  "type": "Annotation",
  "created": "2015-02-01T10:13:40Z",
  "modified": "2015-02-02T20:43:19Z"
  "body": {
    "type": "TextualBody",
    "value": "I REALLY like this page!"
  },
  "target": "http://www.example.com/index.html"
}

5.4 Delete an Existing Annotation

Clients MUST use the DELETE HTTP method to request that an Annotation be deleted by the server. Annotation Servers SHOULD support this method. Clients SHOULD send the ETag of the Annotation in the If-Match header to ensure that it is operating against the most recent version of the Annotation.

If the DELETE request is successfully processed, then the server MUST return a 204 status response. The IRIs of deleted Annotations SHOULD NOT be re-used for subsequent Annotations. The IRI of the deleted Annotation MUST be removed from the Annotation Container it was created in. There are no requirements made on the body of the response, and it MAY be empty.

DELETE /annotations/anno1 HTTP/1.1
Host: example.org
If-Match: "_87e52ce126126"

HTTP/1.1 204 NO CONTENT
Content-Length: 0