VAST REST API Overview

Introduction

The VAST administrative infrastructure is managed by VMS - the VAST Management Server. When you use the VAST Web UI or the VAST CLI to administer VAST, all of your commands and interactions are ultimately with VMS. This interaction is over a REST interface. The architecture of VAST administration looks like this:

The diagram illustrates a VMS architecture where multiple clients, including a web browser and custom applications, interact with a VCLC (VMS Command Line Client) via a VCS REST API, which is hosted on a VSCS server running within a VCM container.

Notice that there is a third option. If you prefer to bypass the VAST-provided management interfaces, you can directly access the underlying REST APIs. This enables you to access (and modify) more advanced information about the system, build your own custom administrative infrastructure, query metrics and load them into other systems, and so on.

Swagger

The VAST REST interface is documented and exposed using Swagger, making it easier to use and understand. To access the Swagger information on the interface, simply change the URL used for the VAST web UI to include/api; for example, 'https://<VMS VIP>/api'. When you do this, you'll be presented with a Swagger interface.

Initially, very little is shown as you need to log in. Click the Session Login button in the upper-right corner, then specify the administrator's userid and password. This is the same id you use to login to the VAST Web UI. Now you'll see all of the REST APIs provided by VMS. These are the same APIs used by the Web UI and VCLI that you use. Thus, you have access to the full power and functionality of the management infrastructure. You'll see a very long page that looks something like this:

The API documentation for VAST includes endpoints such as /api/alarms and /api/callhomeconfigs, which detail operations like presenting alarms or call home configurations via HTTP methods GET and PATCH, with DELETE also available for appropriate endpoints to manage these resources effectively.

You can click on any of those REST methods to learn a bit more about how to call them and even test them. For example, let's use the .../api/clusters/ method to get a list of clusters (today, there is only one). Anyway, go ahead and select the method and then click Try It Out, and you'll see something that looks like this:

The image shows an API endpoint `/api/clusters/` designed to list clusters, with parameters such as `page` and `page_size` to paginate results. Users can execute this API call by clicking the "Execute" button, which will return cluster information in JSON format.

Since this API takes no additional mandatory parameters, you can just click on Execute, and you'll see a generated CURL command and the output from the command - notice it is easily parseable JSON. Very handy for writing your own clients. You'll see something like this. Notice how much more detailed information you get on the cluster.

The screenshot displays a successful GET request to an API endpoint, returning a JSON response with cluster details such as ID, GUID, name, URL, and various space usage metrics like physical and logical space in use and their percentages. The response headers indicate allowed HTTP methods and content type information.

CURL

Notice at the top that the CURL command. You can use that same command to access the REST interface, although you'll need to make small modifications. You'll need to remove the '-H "X-CSRFToken: ..."' portion and then add --insecure to the curl command line and --user --password. That will result in a line that looks roughly like this:

curl -u admin:123456 --insecure -X GET "https://10.100.21.201/api/clusters/" -H "accept: application/json"

Of course, your IP address will be different.

Selected Fields

Almost all of the APIs (metrics don't) also allow you to limit the fields that come back. This is useful if you only want a subset of the full data description for an object. For example, if you are querying information about C-nodes but only want to know about the hostname, name, and ip fields, you can use this query - notice the fields argument.

curl -u admin:123456 --insecure -X GET "https://10.100.201.201/api/cnodes/?fields=id,name,hostname,ip" -H "accept: application/json"

That will return something like this:

Security Sidebar

You might be a little nervous to note that curl is being used with --insecure and that the userid and password is specified on the command line. None of that is required. That's just done to make things simpler in our example. If you specify -u <user> to curl, it will prompt for the password. And of course, if you use an automated tool, then there is no curl command line at all.

The --insecure option simply tells curl not to validate the VAST certificate used over HTTPS. You can certainly assign any certificate you like to your VAST cluster in VMS by going to Settings --> Certificates. And of course, you can tell curl to use different trust stores as needed (--cacert).

You may have also been nervous about the fact that we are using the admin user. Obviously, that user is very powerful. The REST interface honors VAST admin authorization. If you are going to use this in a real production environment, we recommend you create a new administrative user (called manager in VAST) that has just the needed permissions. To create a manager in VMS, go to Security-->Managers and click the + to create a new Manager. The metrics users need only read-only access.

Summary

Now we've shown you that the VAST REST API can be used to directly access administrative functions securely. We've shown you a simple example using curl. From here, you have the knowledge you need to build your own administrative clients. Check the other articles in this section, and swaggerwe'll provide you with a trivial example using Python. We also show how to gather metrics directly from VAST over REST.