Introduction to the API

The API supports create, read, update, and delete operations on datasets, graphmarts, data layers, and steps. The interface also supports read and update operations for artifact access control lists, upload, download, and delete operations for models, run and cancel operations for unstructured pipelines, import and export operations for migration packages, and read operations for dynamic launch configurations and static AnzoGraph instances.

This topic gives a summary of the API request URL, endpoints and methods, URI encoding requirements, and error handling.

• Request URL
• Endpoints and Methods
• URI Encoding Requirements
• Error Handling

Request URL

The path in the URL that you use to access the REST API endpoints (as well as the documentation on your Anzo server) differs depending on the version of Anzo that is installed:

• In 5.4.1 releases, the URL is https://<hostname>/api/v1/<endpoint>.
• In 5.4.2+ releases, the URL is https://<hostname>/api/<endpoint>.

The v1 in the path was removed in 5.4.2. The URL to access the documentation on your Anzo server was also changed from https://<hostname>/api/v1/docs/index.html in 5.4.1 to https://<hostname>/api/docs/index.html in 5.4.2.

Endpoints and Methods

There is an endpoint for each type of Anzo artifact or object (dataset, edition, model, graphmart, layer, step, etc.). Each endpoint supports a subset or all of the following methods:

• POST or PUT for create
• GET for reads
• PATCH for updates
• DELETE for delete

URI Encoding Requirements

When including a URI (e.g., a graphmart, layer, or step URI) in a request URL, the URI must be URL-encoded. The following example shows a layer URI, http://cambridgesemantics.com/Layer/858c521bc7d84364a5a2112e38dc0b52, that has been URL-encoded:

http%3A%2F%2Fcambridgesemantics.com%2FLayer%2F858c521bc7d84364a5a2112e38dc0b52

The encoded value should be used in the request URL. For example, the following request retrieves the status of the layer:

http://10.100.0.10:8080/api/layers/http%3A%2F%2Fcambridgesemantics.com%2FLayer%2F858c521bc7d84364a5a2112e38dc0b52/status

An error message such as the one below indicates that a request URL included a URI that was not URL-encoded:

{
  "summary": "Rest API Error: No handler found for GET /api/graphmarts/http://cambridgesemantics.com/Graphmart/811ece67d61e436cb128a929797b68df",
  "detail": "No handler found for GET /api/graphmarts/http://cambridgesemantics.com/Graphmart/811ece67d61e436cb128a929797b68df"
}

To resolve the error, encode the URI as a URL and then resend the request.

Error Handling

Errors returned from the API contain a summary and detailed message. Stack traces from the server are not included in API responses. Stack traces can be obtained via the server logs. The documentation describes the error codes and response details.