APIs

Getting Started with the Volterra API

This document is intended to be QuickStart guide to using the Volterra API. For detailed information, please visit the website to learn more about Volterra API Concepts and the API Reference.


Prerequisites

All Volterra API requests are required to be authenticated using either an API Token or API Certificate. Click here to view instructions on how to obtain an API Token or API Certificate from the VoltConsole.


Authentication

Volterra API requests support two types of authentication: API Token and API Certificate. The following information explains how you can create authenticated API requests using curl, but can also be incorporated into other tools such as Postman.

  1. API Token Authentication Volterra API requests using the API Token authentication method must provide the token in the Authorization request header. The following sample API request is used to list tenant namespaces for free or individual plans:
curl http://console.ves.volterra.io/api/web/namespaces \
    -H "Authorization: APIToken <token value>"

For organization plans, the following sample API request is used to list tenant namespaces:

curl https://<tenant>.console.ves.volterra.io/api/web/namespaces \
-H "Authorization: APIToken <token value>"

Where <tenant> is replaced with the tenant name and <token value> is replaced with the API Token created in the VoltConsole. Complete examples:

Free or Team Plan

curl http://console.ves.volterra.io/api/web/namespaces \
    -H "Authorization: API Token RGFCZWFyc1N0aWxsU3Vjaw=="

Organization Plan

curl https://acmepackingco.console.ves.volterra.io/api/web/namespaces \
-H "Authorization: APIToken QWFyb25Sb2RnZXJzMTI="

Note: Requests using API Token authentication will have the same RBAC assigned as the user who created the API Token.

  1. API Certificate Authentication

    Volterra API requests using the API Certificate authentication method must provide the client certificate and password as part of the request. The following sample API request is used to list tenant namespaces for free or individual plans:

curl https://console.ves.volterra.io/api/web/namespaces --cert-type P12 \
    --cert <api-creds>:<password>

For organization plans, the following sample API request is used to list tenant namespaces:

curl https://<tenant>.console.ves.volterra.io/api/web/namespaces --cert-type P12 \
--cert <api-creds>:<password>

Where <tenant> is replaced with the tenant name, <api-creds> is replaced with the local path to the p12 client certificate file, and is replaced with the password for the p12 certificate. Complete examples:

Free or Team Plan


curl https://console.ves.volterra.io/api/web/namespaces --cert-type P12 \
    --cert /Users/staleys/console.ves.volterra.io.api-creds.p12:TrubiskyPick6!

Organization Plan

curl https://acmepackingco.console.ves.volterra.io/api/web/namespaces --cert-type P12 \
--cert /Users/acme/acmepackingco.console.ves.volterra.io.api-creds.p12:GoPackGo!

Note: It is recommended to use the full path of the client certificate instead of relative paths.


Building a Request

Except for a handful API requests, all Volterra API requests must begin with the following URL formats:

Free or Team Plan

https://console.ves.volterra.io/{service_prefix}/namespaces/{namespace}/{kind}

Organization Plan

https://<tenant>.console.ves.volterra.io/{service_prefix}/namespaces/{namespace}/{kind}

Where <tenant> represents the tenant name for organization plans, {service_prefix} represents the Volterra service handling the request, {namespace} represents the namespace that the object belongs to, and {kind} represents the object type.

Note: From this point forward in the documentation, all examples provided will be for organization plans that include a tenant name. For team or individual plans, disregard the tenant name placeholder and use console.ves.volterra.io as the hostname.

Client API requests are served by multiple Volterra services using the same endpoint address (e.g. https://<tenant>.console.ves.volterra.io), but different service prefixes.

Service prefixes are used to identify the Volterra service that will process the request. The following table is a list of service prefixes and their corresponding functionality:

Prefix Functional Area
/api/config/ Configuration
/api/data/ Monitoring and Analytics
/api/kms/ Cryptographic Key Management
/api/ml/data/ Machine Learning
/api/secret_management/ Secret Management
/api/waf/ Web Application Firewall
/api/web/ User Access Management
/api/vk8s/ Virtual Kubernetes

Namespaces can be thought of as "administrative" domains, or isolation within a tenant. Objects are grouped within namespaces and API requests are performed on these objects. More information about namespaces can be found here.

By default, each tenant is created with three built-in namespaces: default, shared, and system. Users can also create additional user-defined namespaces and apply role-based access controls.

There are also many kinds of objects that belong to a namespace, for example sites, fleets, network_interfaces, users, etc. Let's have a closer look at an example API request for the sites object:

curl https://acmepackingco.console.ves.volterra.io/api/config/namespaces/system/sites \
-H "Authorization: APIToken QWFyb25Sb2RnZXJzMTI="

This API request will list all objects of type sites in the system namespace:

{
    "items": [
        {
            "tenant": "ves-io",
            "namespace": "system",
            "name": "ams9-ams",
            "uid": "ca7c6038-064a-44d4-9141-4c87fa3d609c",
            "labels": {
                "ves.io/country": "ves-io-nl",
                "ves.io/region": "ves-io-amsterdam",
                "ves.io/siteName": "ves-io-ams9-ams",
                "ves.io/siteType": "ves-io-re"
            },
            "owner_view": null,
            "object": null,
            "get_spec": null,
            "status_set": []
        },
        {
            "tenant": "acmepackingco",
            "namespace": "system",
            "name": "dev-site",
            "uid": "0e9db6e9-7b7f-4727-a93b-5787d0f7d938",
            "labels": {
                "host-os-version": "centos-7-2004-8",
                "hw-model": "vmware-virtual-platform",
                "hw-serial-number": "vmware-56-4d-26-16-13-2b-41-12-5a-3f-82-01-b3-f0-7d-70",
                "hw-vendor": "vmware-inc",
                "hw-version": "none",
                "provider": "VMWARE",
                "ves.io/fleet": "dev-site",
                "ves.io/siteType": "ves-io-ce"
            },
            "owner_view": null,
            "object": null,
            "get_spec": null,
            "status_set": []
        },
        ...
    ]
}

Note: output has been truncated for brevity

If we want to drill down further and retrieve information about the site called dev-site, we can append the name of the site to the end of the URL to specify the exact object we want to retrieve:

curl https://acmepackingco.console.ves.volterra.io/api/config/namespaces/system/sites/dev-site \
-H "Authorization: APIToken QWFyb25Sb2RnZXJzMTI="

This API request will return all information about the dev-site object:

{
    "object": {
        "metadata": {
            "name": "dev-site",
            "namespace": "system",
            "uid": "0e9db6e9-7b7f-4727-a93b-5787d0f7d938",
            "labels": {
                "host-os-version": "centos-7-2004-8",
                "hw-model": "vmware-virtual-platform",
                "hw-serial-number": "vmware-56-4d-26-16-13-2b-41-12-5a-3f-82-01-b3-f0-7d-70",
                "hw-vendor": "vmware-inc",
                "hw-version": "none",
                "provider": "VMWARE",
                "ves.io/fleet": "dev-site",
                "ves.io/siteType": "ves-io-ce"
            },
            "annotations": {},
            "description": "",
            "disable": false
        },
        "system_metadata": {
            "uid": "0e9db6e9-7b7f-4727-a93b-5787d0f7d938",
            "creation_timestamp": "2020-08-22T06:39:15.985533844Z",
            "deletion_timestamp": null,
            "modification_timestamp": "2020-08-27T00:06:07.091655050Z",
            "initializers": null,
            "finalizers": [],
            "tenant": "acmepackingco",
            "creator_class": "akar",
            "creator_id": "",
            "creator_cookie": "",
            "trace_info": "220e7acb58986ac:664be9619c251e1:220e7acb58986ac:1",
            "object_index": 2779,
            "namespace": [
                {
                    "kind": "namespace",
                    "uid": "d853b0a3-dcf4-400a-b272-23a750ac436f",
                    "tenant": "acmepackingco",
                    "namespace": "",
                    "name": "system"
                }
            ],
            "owner_view": null
        }
    }
}

Note: output has been truncated for brevity.

These two example API requests have retrieved information from the Volterra API using the GET request method. API requests can also be made using POST, PUT, and DELETE request methods to create, modify, and delete objects. Here are some example API requests to create a new site, modify the site, and then delete the site:

Create Site

To create a new site called grb-site with the minimum required parameters, we can use the following example API request:

curl https://acmepackingco.console.ves.volterra.io/api/config/namespaces/system/sites \
    -H "Authorization: APIToken QWFyb25Sb2RnZXJzMTI=" \
    -H "Content-Type: application/json" \
    -X POST -d '{"metadata":{"name":"grb-site"}}'

Using the API specification for Create Site, we can determine the minimum required parameters for the API request:

create api
Figure: Create API

The "Path Parameters" informs us of the required information to insert into the URI to create a new site:

post
Figure: Path Parameters for Create API

Since sites belongs to the system namespace, the URI for this request becomes:

/api/config/namespaces/system/sites

Notice that the HTTP request method is type POST, indicating we are sending information to the Volterra API server and that we should set the request method in the curl request using the "-X" parameter. The "Request Body Schema" informs us of the minimum required information to send to in the request to create a new site:

post
Figure: Request Body Schema

In the "metadata" section, the only required information to include in the request body is the "name":

name
Figure: Meta Data Required Field

In the "spec" section, while there are many parameters that we can include in the site creation, we observer that there are no required parameters in order to create a new site.

The minimum required information in the request body therefore becomes:

{
    "metadata": {
        "name": "grb-site"
    }
}

And is denoted in the curl request with the "-d" parameter, followed by the JSON payload. If the API request is successful, the response is a JSON payload with information about the site that was created:

{
    "metadata": {
        "name": "grb-site",
        "namespace": "system",
        "labels": {},
        "annotations": {},
        "description": "",
        "disable": false
    },
    "system_metadata": {
        "uid": "2bc9d3b4-91f3-4522-8626-381e9ac6abad",
        "creation_timestamp": "2020-08-27T22:57:20.993696315Z",
        "deletion_timestamp": null,
        "modification_timestamp": null,
        "initializers": null,
        "finalizers": [],
        "tenant": "acmepackingco",
        "creator_class": "prism",
        "creator_id": "arod12@acmepackingco.com",
        "object_index": 2893,
        "owner_view": null
    },
    "spec": {
        "site_type": "INVALID",
        "address": "",
        "coordinates": null,
        "volterra_software_version": "",
        "connected_re": [],
        "connected_re_for_config": [],
        "inside_vip": "",
        "outside_vip": "",
        "vip_vrrp_mode": "VIP_VRRP_INVALID",
        "site_to_site_network_type": "VIRTUAL_NETWORK_SITE_LOCAL",
        "site_to_site_tunnel_ip": "",
        "volterra_software_overide": "SITE_SOFTWARE_OVERRIDE_SITE",
        "bgp_router_id": "",
        "bgp_peer_address": "",
        "inside_nameserver": "",
        "outside_nameserver": "",
        "desired_pool_count": 0,
        "tunnel_type": "SITE_TO_SITE_TUNNEL_IPSEC_OR_SSL",
        "operating_system_version": "",
        "site_state": "ONLINE",
        "tunnel_dead_timeout": 0,
        "region": "",
        "ce_site_mode": "CE_SITE_MODE_INGRESS_EGRESS_GW"
    }
}

Notice that the site was created with many default values since we did not specify more than the minimum required parameters to create a new site.


Replace Site

To replace a site (e.g. modify an existing site), we can use the following example API request to set the latitude and longitude coordinates for the site:

curl https://acmepackingco.console.ves.volterra.io/api/config/namespaces/system/sites/grb-site \
    -H "Authorization: APIToken QWFyb25Sb2RnZXJzMTI=" \
    -H "Content-Type: application/json" \
    -X PUT -d '{"metadata":{"name":"grb-site"},"spec":{"coordinates":{"latitude":"44.5013","longitude":"-88.0622"}}}'

Using the API specification for Replace Site, we can determine the required parameters for the API request:

replace api
Figure: Replace Site API

The "Path Parameters" informs us of the required information to insert into the URI to replace a site:

post replace
Figure: Path Parameters for Replace API

Since sites belongs to the system namespace and the site we want to replace is called grb-site, the URI for this request becomes:

/api/config/namespaces/system/sites/grb-site

Notice that the HTTP request method is type PUT, again indicating we are sending information to the Volterra API server and that we should set the request method in the curl request using the "-X" parameter.

The "Request Body Schema" informs us that the required information to change the latitude and longitude coordinates of the site are metadata.name, spec.coordinates.latitude, and spec.coordinates.longitude:

coords
Figure: Request Body Schema Coordinates

The required information in the request body therefore becomes:

{
    "metadata": {
        "name": "grb-site"
    },
    "spec": {
        "coordinates": {
            "latitude": "44.5013",
            "longitude": "-88.0622"
        }
    }
}

And is denoted in the curl request with the "-d" parameter, followed by the JSON payload. If the API request is successful, the response is an empty JSON payload with an HTTP 200 response code.


Delete Site

To delete a site, we can use the following example API:

curl https://acmepackingco.console.ves.volterra.io/api/config/namespaces/system/sites/grb-site \
    -H "Authorization: APIToken QWFyb25Sb2RnZXJzMTI=" \
    -X DELETE

Using the API specification for Delete Site, we can determine the required parameters for the API request:

delete api
Figure: Delete API

The "Path Parameters" indicates the required information to insert into the URI to delete a site

post del api
Figure: Delete API Path Parameters

Since sites belongs to the system namespace and the site we want to delete is called grb-site, the URI for this request becomes:

/api/config/namespaces/system/sites/grb-site

Notice that the HTTP request method is type DELETE and that we should set the request method in the curl request using the "-X" parameter.

Since there is no "Request Body Schema" for Delete Site, no JSON payload is required in the API request to delete the site. If the API request is successful, the response is an empty JSON payload with an HTTP 200 response code.


TL;DR

  • All Volterra API requests are required to be authentication.
  • Information on how to request client credentials can be found here.
  • Authenticated API requests use the Authorization: APIToken <token> request header or p12 client certificate.
  • Most API requests use the following format: https://<tenant>.console.ves.volterra.io/{service_prefix}/namespaces/{namespace}/{kind}
  • Reference the API Specification for detailed information on how to format requests.