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 GATE Cloud REST APIs can be found on this page.

2. Browsing the shop

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

List the available pipelines and machines in the GATE Cloud 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

<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:

<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 or machine

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

Request format

<reserve>
  <quanitity>1</quantity>
</reserve>

{
  "quantity":1
}

• quantity - the number of jobs based on this pipeline (or instances of this machine) 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-GATECloud-Payment: OK

Items with no up-front charge do not require this header.

Response format

<reserveResult>
  <status>OK</status>
  <job>{jobUrl}</job>
  <machineCount>{number}</machineCount>
</reserveResult>

{
  "status":"OK",
  "jobs":[
    "{jobUrl}"
  ],
  "machineCount":1
}

The response will include one or other of:

• jobUrl - the URL at which the job can be configured using the job management API.
• machineCount - if the item to be reserved is a cloud machine, the number of such machines that have been reserved. The process of reserving machines is asynchronous, so the precise machine IDs will not be known for a few minutes.

If the quantity parameter was greater than 1 there will be several <job> elements (XML) or several entries in the jobs array (JSON), or machineCount will be greater than 1, as appropriate to the item reserved.