OnlineApi - GateNLP/cloud-client GitHub Wiki

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.

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. You will need to enable the "online API" permission for the API key (which should be set by default when creating a new key).

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

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
}

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).