Getting Started

Formulating the Endpoint URL

To call a VAST DataEngine API operation:

• Send a request to an endpoint formed as:

      https://VMS_VIP/api/dataengine/OBJECT/

The endpoint URL includes:

• VMS_VIP, an IP specific to the cluster for accessing the VAST Management System (VMS) for the cluster.

• OBJECT, an object class such as triggers, functions or pipelines.

For example, if the cluster's VMS virtual IP is at 192.0.2.0, to request the /functions endpoint, you would use this URL:

https://192.0.2.0/api/dataengine/functions/

• Include one of the supported forms of authentication.

• If the requesting user is a cluster admin user, you must include the tenant in the request. Tenant properties are globally supported for this purpose. and may not be explicitly documented for the individual endpoint.

  You can pass one of the following properties in the body parameter (the payload) of the request:

  • tenant_guid with the tenant's GUID (globally unique ID).

  • tenant_id with the cluster's object ID for the tenant.

  • tenant_name with the tenant name.

• Specify one of several methods:

  • POST to create a resource of a given type,

  • PATCH to change one or more properties of a given resource,

  • DELETE to delete a specified resource, or

  • GET to return information about one or more resources.

  Most endpoints can be accessed by several methods. For example, you can send a POST request to the /triggers endpoint to create a new trigger, a DELETE request to the /triggers/{guid} endpoint to delete a trigger, and so on.

HTTPS Encryption

The VMS API supports requests only over the HTTPS protocol, the secure version of the HTTP protocol in which requests and responses are encrypted.

Paginating the Response

The API supports response pagination.

To specify the number of results to return in a response, append the limit parameter to the URL of a REST API request like this:

?limit=<integer>

<integer> here is the number of results you want to get in the first response.

The response then includes a structure called pagination that contains next_cursor and previous_cursor properties, like this, for example:

    {next_cursor:<next cursor value>, previous_cursor: None}.

To go the second page of results, you would then send another request, specifying the provided next_cursor value using another query parameter, cursor, like this:

?limit=100&cursor=<next cursor value>

When you return the nth page of results, you can use the previous_cursor value in the pagination response to display the (n-1)th page of results. For example, suppose the pagination structure in your fourth page of results includes previous_cursor: <previous cursor value>, then you can send cursor=<previous cursor value> to return the third page of results.

Error Response Codes

The VMS API uses conventional HTTP response codes to indicate the success or failure of an API request.

User Types, Permissions and Specifying a Tenant

Requests are authorized according to the permissions of the authenticating user. Some of the endpoints require VMS role based access permissions that can be granted to tenant admin users. Other endpoints require either VMS permission for a tenant admin user or a cluster admin user or permission that can be granted to users with type application user through an identity policy.

When using the VAST DataEngine API endpoints as a cluster admin user, you can include one of the following properties in the body parameter (payload) of the request to specify the tenant:

• tenant_guid with the tenant's GUID (globally unique ID).

• tenant_id with the cluster's object ID for the tenant.

• tenant_name with the tenant name.

User provisioning for VAST DataEngine can be done using the VMS REST API.