Storage API Documentation

[BigBlueHat]

AnnotatorJS's Storage API documentation--which, since we use a fork of it also serves for our docs atm--are fine for humans, but I wanted something that could be used to stub out other backend implementations...so docs for humans and robots was needed. :smile:

I've begun crafting some RAML docs for the Storage API: https://anypoint.mulesoft.com/apiplatform/repository/public/organizations/2169/apis/2849/versions/2846/files/root (I'll add it as a separate comment also).

This was driven by a few conversations with partners who have an interest in building their own implementation of the API on their choice of database (vs. using annotator-store or h directly).

More to come.

[BigBlueHat]

Here's the RAML as it stands so far:

#%RAML 0.8
title: Annotator Store
version: 2.0.0
baseUri: https://hypothes.is/api/
mediaType: application/json

/:
  displayName: Service Description
  get:
    description: Root URL of the Storage API. Provides links to the other endpoints.
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "message": "Annotator Store API",
                "links": {
                  "search_raw": {
                    "url": "https://hypothes.is/api/search_raw",
                    "method": "GET/POST",
                    "desc": "Advanced search API -- direct access to ElasticSearch. Uses the same API as the ElasticSearch query endpoint."
                  },
                  "search": {
                    "url": "https://hypothes.is/api/search",
                    "method": "GET",
                    "desc": "Basic search API"
                  },
                  "annotation": {
                    "read": {
                      "url": "https://hypothes.is/api/annotations/:id",
                      "method": "GET",
                      "desc": "Get an existing annotation"
                    },
                    "create": {
                      "query": {
                        "refresh": {
                          "type": "bool",
                          "desc": "Force an index refresh after create (default: true)"
                        }
                      },
                      "url": "https://hypothes.is/api/annotations",
                      "method": "POST",
                      "desc": "Create a new annotation"
                    },
                    "update": {
                      "query": {
                        "refresh": {
                          "type": "bool",
                          "desc": "Force an index refresh after update (default: true)"
                        }
                      },
                      "url": "https://hypothes.is/api/annotations/:id",
                      "method": "PUT",
                      "desc": "Update an existing annotation"
                    },
                    "delete": {
                      "url": "https://hypothes.is/api/annotations/:id",
                      "method": "DELETE",
                      "desc": "Delete an annotation"
                    }
                  }
                }
              }
/annotations:
  post:
    description: "Create a new annotation"
    body:
      application/json:
        example: |
          {
            "text": "Annotation text"
          }
    responses:
      401:
        body:
          application/json:
            example: |
              "Cannot authorize request (create annotation). Perhaps you're not logged in as a user with appropriate permissions on this annotation? (user=None, consumer=None)"
  /{id}:
    get:
      description: Get an existing annotation
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "text": "As in null?",
                  "updated": "2014-08-27T18:48:01.007982+00:00",
                  "id": "KLUGtTMjTUSOPVvACd-dNA",
                  "consumer": "00000000-0000-0000-0000-000000000000",
                  "permissions": {
                    "read": [
                      "acct:BigBlueHat@hypothes.is",
                      "group:__world__"
                    ],
                    "update": [
                      "acct:BigBlueHat@hypothes.is"
                    ],
                    "delete": [
                      "acct:BigBlueHat@hypothes.is"
                    ],
                    "admin": [
                      "acct:BigBlueHat@hypothes.is"
                    ]
                  },
                  "uri": "http://scalar.usc.edu/dev/dev-test-book-cantaloupe/index",
                  "document": {
                    "prism": {},
                    "dc": {},
                    "reply_to": [],
                    "highwire": {},
                    "eprints": {},
                    "facebook": {},
                    "title": "Home",
                    "twitter": {},
                    "link": [
                      {
                        "href": "http://scalar.usc.edu/dev/dev-test-book-cantaloupe/index"
                      },
                      {
                        "href": "http://scalar.usc.edu/dev/dev-test-book-cantaloupe/index",
                        "type": "",
                        "rel": "canonical"
                      }
                    ],
                    "favicon": "http://scalar.usc.edu/dev/system/application/views/arbors/html5_RDFa/favicon_16.gif"
                  },
                  "target": [
                    {
                      "selector": [
                        {
                          "startOffset": 57,
                          "startContainer": "/article[1]/span[1]/div[1]/div[2]",
                          "type": "RangeSelector",
                          "endOffset": 62,
                          "endContainer": "/article[1]/span[1]/div[1]/div[2]"
                        },
                        {
                          "start": 517,
                          "type": "TextPositionSelector",
                          "end": 522
                        },
                        {
                          "prefix": "t, consectetur adipiscing elit. ",
                          "suffix": " imperdiet lorem vitae felis gra",
                          "type": "TextQuoteSelector",
                          "exact": "Nulla"
                        }
                      ],
                      "source": "http://scalar.usc.edu/dev/dev-test-book-cantaloupe/index",
                      "pos": {
                        "top": 212.3333282470703,
                        "height": 19
                      },
                      "quote": "Nulla",
                      "$$hashKey": "00P",
                      "showDiff": false
                    }
                  ],
                  "tags": [
                    "embed.js",
                    "scalar"
                  ],
                  "reply_list": [],
                  "quote": "Nulla",
                  "created": "2014-08-26T14:06:52.563308+00:00",
                  "user": "acct:BigBlueHat@hypothes.is"
                }

[tilgovi]

Neat.

[BigBlueHat]

Replaced by #2099

[judell]

I want to update the docs with what I learned last week about the /search API. Trying to sort out where everything is. Have encountered (so far):

https://github.com/hypothesis/h/blob/master/docs/api.rst

https://github.com/openannotation/annotator/blob/3359eabb13fa7e422174df76cba421c5c87d4421/doc/storage.rst

http://docs.hypothesis.apiary.io/

https://h.readthedocs.org/en/latest/api.html

Seems like https://github.com/hypothesis/h/blob/master/docs/api.rst should be the canonical source, and https://h.readthedocs.org/en/latest/api.html the canonical human-readable view?

Intending to tweak the former in my fork of it, this happened:

judell Did https://github.com/hypothesis/h/blob/master/docs/api.rst used to be fully viewable in GitHub? judell exploring at http://rst.ninjs.org/, looks like this pattern -- .. http:get:: /api/search -- borks the viewer (Unknown directive type "http:get".)

[tilgovi]

You need sphinxcontrib-httpdomain for these HTTP documentation directives, so an online editor is probably not going to work.

Our repo is the source for h.readthedocs.org. So https://github.com/hypothesis/h/blob/master/docs/api.rst => https://h.readthedocs.org/en/latest/api.html

Similarly, for annotator.

[judell]

So if I want to propose changes to the .rst, I should view my changes before sending a PR using ____?

[tilgovi]

If you want to see what it will look on readthedocs.org, then you want to run make html from the docs directory.