GATE Cloud Shop REST API

1. Introduction

This document describes the REST API provided by GATE Cloud to browse the available pipelines and reserve annotation jobs that use a particular pipeline. General information about AnnoMarket REST APIs can be found on this page.

2. Browsing the shop

GET https://cloud.gate.ac.uk/api/shop

List the available pipelines in the AnnoMarket shop. By default all pipelines available to the authenticating user are listed, but query parameters can be used to limit the search based on tags or to fetch the results in smaller chunks.

Query string parameters

  • tag (optional) include only items with a particular tag or tags. Multiple tags may be specified and will be "AND"-ed, i.e. only items that have all the specified tags will be listed.
  • max (optional) the maximum number of items to return. By default all matching items are included.
  • offset (optional) the offset of the first item to include. The max and offset parameters together allow for pagination - max=10 would return the first ten items, then max=10&offset=10 would return the eleventh to the twentieth, etc.

Example: https://cloud.gate.ac.uk/api/shop?tag=English&tag=News would list all pipelines tagged as both "English" and "News".

Response format

XML JSON
<items>
  <item>
    <id>1</id>
    <name>ANNIE Named Entity Recogniser</name>
    <shortDescription>ANNIE is....</shortDescription>
    <detailUrl>https://cloud.gate.ac.uk/api/shop/item/1</detailUrl>
    <price setup="0.0" hour="0.8" mib="0.0" />
    <onlineUrl>https://cloud-api.gate.ac.uk/...</onlineUrl>
  </item>
  ...
</items>
[
  {
    "id":1,
    "name":"ANNIE Named Entity Recogniser",
    "shortDescription":"ANNIE is....",
    "detailUrl":"https://cloud.gate.ac.uk/api/shop/item/1",
    "price":{
      "setup":0, "hour":0.8, "mib":0
    },
    "onlineUrl":"https://cloud-api.gate.ac.uk/..."
  },
  ...
]

The onlineUrl is the URL of the on-line API endpoint for this pipeline, which can be used to process documents one at a time. The detailUrl can be used with a POST request to reserve an instance of the pipeline to run a larger batch processing job.

3. Details of a single item

GET https://cloud.gate.ac.uk/api/shop/item/{itemId}

Response format

Exactly as for the list of items, but without the outer wrapper:

XML JSON
<item>
  <id>1</id>
  <name>ANNIE Named Entity Recogniser</name>
  <shortDescription>ANNIE is....</shortDescription>
  <detailUrl>https://cloud.gate.ac.uk/api/shop/item/1</detailUrl>
  <price setup="0.0" hour="0.8" mib="0.0" />
  <onlineUrl>https://cloud-api.gate.ac.uk/...</onlineUrl>
</item>
{
  "id":1,
  "name":"ANNIE Named Entity Recogniser",
  "shortDescription":"ANNIE is....",
  "detailUrl":"https://cloud.gate.ac.uk/api/shop/item/1",
  "price":{
    "setup":0, "hour":0.8, "mib":0
  },
  "onlineUrl":"https://cloud-api.gate.ac.uk/..."
}

4. Reserve an annotation job

POST https://cloud.gate.ac.uk/api/shop/item/{itemId}

Request format

XML JSON
<reserve>
  <quanitity>1</quantity>
</reserve>
{
  "quantity":1
}
  • quantity - the number of jobs based on this pipeline to reserve (typically 1)

Note that if the item has a non-zero setup charge then this call will require payment. To confirm that you are willing to accept such a charge you must include an HTTP header with the call:

X-AnnoMarket-Payment: OK

Items with no up-front charge (i.e. all pipelines in the beta test phase) do not require this header.

Response format

XML JSON
<reserveResult>
  <status>OK</status>
  <job>{jobUrl}</job>
</reserveResult>
{
  "status":"OK",
  "jobs":[
    "{jobUrl}"
  ]
}

If the quantity parameter was greater than 1 there will be several <job> elements (XML) or several entries in the jobs array (JSON).