OnlineApi

Ian Roberts edited this page Jun 10, 2018 · 3 revisions

The class uk.ac.gate.cloud.online.OnlineApiManager is the main entry point if you want to annotate documents online sending requests and immediately receiving results.

Creating a client

To create a client instance you need your API key ID and password - if you do not have an API key you can generate one from your account page on the GATE Cloud website.

OnlineApiManager mgr = new OnlineApiManager("<key id>", "<password>");

Using the OnlineApi client

To call the online API you need to know the endpoint URL of the pipeline you want to call. This is available from the shop page on the GATE Cloud website, and programatically via the onlineUrl property of any Item obtained from the shop API. Given an endpoint URL, you can obtain an ApiEndpoint from the manager

ApiEndpoint endpoint = mgr.getEndpoint(url);

ApiEndpoint provides a variety of call methods to call the target service. They can take the document to be annotated from an InputStream, or as an instance of the functional interface StreamWritable, which specifies a method that receives an OutputStream and should write the document content to that. Other required parameters are the MIME type identifying the input document format, and the required response format (JSON, GATE XML or FastInfoset). Optionally, a comma-separated list of annotation selectors can be provided to customise the annotation types returned from the service. If the selector parameter is null the service's default selectors are used.

The call methods return an InputStream from which the response can be read.

ObjectMapper mapper = new ObjectMapper();
String str = "The text to process";
try(InputStream stream = endpoint.call((out) -> out.write(str.getBytes("UTF-8")), "text/plain", ResponseType.JSON, null)) {
  ObjectNode response = (ObjectNode)mapper.readTree(stream);
  // process the response JSON appropriately
} catch(IOException e) {
  // exception handling omitted for clarity
}

Service metadata

The metadata() method on ApiEndpoint returns metadata about the service, including the default set of annotation selectors, and any additional selectors representing annotation types that the pipeline can produce but does not return by default.

ServiceMetadata metadata = endpoint.metadata();
System.out.println("Service name: " + metadata.name);
System.out.println("Default annotations: " + metadata.defaultAnnotations);
// etc.

The returned metadata also includes details about the available daily quota and the "cost" of each call, allowing you to estimate how many requests you can make to the service within any 24 hour period. The exact values for quota and cost are not important, the key is that dividing the quota by the cost will give the number of daily requests you could make to this service (assuming you do not call any other services in the same period - the quota is shared across all GATE Cloud services).

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.