Zoomdata Version

Administrative Framework Overview

THE APIs

The Zoomdata Administrative Framework provides a REST API with methods for retrieving, updating, and deleting Zoomdata metadata pertaining to accounts, connections, users, and so forth. For an up-to-date description of methods and Swagger reference documentation for the APIs, see the Zoomdata developer zone .

Authentication

The API currently uses basic access authentication. Most actions require admin-level access to the particular account manipulated using the API. Supervisor credentials can be used to access any account.

Versioning

Each version of the API maintains backward compatibility with previous versions. The HTTP Accepts/Content-type header is used to version the resources that are produced and used by the API. When sending data to or receiving data from the API, you must use the appropriate HTTP header.

When working with the API, you should explicitly set the version of the API that you want to use. For example, in curl requests, you would include the --header parameter as shown below.

# For submitting data
curl --header "Content-type: application/vnd.zoomdata.v1+json" ...

# Consuming data
curl --header "Accept: application/vnd.zoomdata.v1+json,application/vnd.zoomdata+json" ...

To always use the latest version of Zoomdata, use the generic media type: application/vnd.zoomdata+json .

The approach of always using the latest version presents a risk. Because this approach does not tie calls to specific API versions, if the latest version changes, your integration may break. It is safer to tie your API calls to specific versions.

The current API media type version will be sent as a header, X-Zoomdata-Media-Type , in the response to every API request.

The rule for specifying media types is simple. Always include the generic media type application/vnd.zoomdata+json and, if you specify a particular version, always put it first. For example:

  • Correct: application/vnd.zoomdata.v1+json,application/vnd.zoomdata+json
  • Incorrect: application/vnd.zoomdata+json, application/vnd.zoomdata.v1+json

HATEOAS Architecture

The Zoomdata API implements the HATEOAS architectural pattern. Most resources returned by the API have a links element. The links elements is an array of objects, each with two properties:

  • rel : short description of how this link relates to the parent object
  • href : the actual link value

Every resource will at least have a rel: "self" link, which is the canonical reference to that object. You can use the other links to explore the relations of a given object, for example, the users in an account or the sources tied to a connection. There are examples of links elements below.

data: [
{...},
{  created: {...},
lastModified: {...},
email: "[email protected]",
username: "adam",
fullName: "Adam Appleton",
enabled: true,
administrator: false,
links: [
{ rel: "self",
href: "https://developer.zoomdata.com:443/zoomdata/api/users/12345678900987654321" },
{ rel: "self.by.username",
href: "https://developer.zoomdata.com:443/zoomdata/api/users/username/adam" },
{ rel: "self.by.email",
href: "https://developer.zoomdata.com:[email protected]" },
{ rel: "account",
href: "https://developer.zoomdata.com:443/zoomdata/api/accounts/09876543211234567890" },              { rel: "groups",
href: "https://developer.zoomdata.com:443/zoomdata/api/users/13579086422468097531/groups" }
] },
...

API Entry Point

The initial entry point to the API is http:// [host] : [port] / [context] /api , for example, http://localhost:8080/zoomdata/api . This URL points to the root API resources that you can use to browse through the API.

The /service/ Path

Some functions of the Zoomdata client application call APIs using a /service/ path.  Except where noted in Zoomdata's developer documentation, endpoints that use the /service/ path are for Zoomdata's internal use only.

If you build an application with Zoomdata's internal-use APIs, you subject it to a high risk of unexpected breakage.

APIs on the /service/ path that are safe to use include, for example, the /service/sources/key endpoint.

Reference Documentation

Zoomdata maintains Swagger-based reference materials for the Administrative Framework's APIs. It is found at https://developer.zoomdata.com/2.2/docs/rest-api/ . In this testing environment, you can experiment with the APIs features.