F5 Distributed Cloud Services APIs

Objective

This document provides information on how to use the F5 Distributed Cloud Services API. For detailed information, see the website to learn more.

Prerequisites

All 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 F5® Distributed Cloud Console (Console).

Authentication

The 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.

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 Console. Complete examples:

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.

API Certificate Authentication

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 <password> is replaced with the password for the p12 certificate. Complete examples:

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 the API requests must begin with the following URL formats:

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 F5 Distributed Cloud's 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.

Client API requests are served by multiple F5 Distributed Cloud's 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 F5 Distributed Cloud's service that will process the request. The following table is a list of service prefixes and their corresponding functionality:

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, and more. 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 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:

Figure: Create API

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

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 F5 Distributed Cloud Services 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:

Figure: Request Body Schema

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

Figure: Meta Data Required Field

In the "spec" section, while there are many parameters that we can include in the site creation, we observe 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:

Figure: Replace Site API

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

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 F5 Distributed Cloud Services 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:

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, 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:

Figure: Delete API

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

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.

Note: The following apply:

• All API requests are required to be authenticated.
• Authenticated API requests use the Authorization: APIToken <token> request header or p12 client certificate.
• Most API requests use the https://<tenant>.console.ves.volterra.io/{service_prefix}/namespaces/\{namespace\}/{kind} format.

Note: If you pass a namespace parameter in both the URI path and the body with different values for each, the namespace from the PATH URI overwrites the value in the body.

Deprecating APIs

The APIs being deprecated are indicated by means of specific headers in the response. A field or set of fields of an API being deprecated is indicated using specific headers in either response or request. In this context, a deprecating API means that it is currently accepted but under the process of removal. The following apply when an API is being deprecated:

• When an API(<http_method + URL>) is deprecated, the x-volterra-rpc-deprecated header with value as true is sent in the response.
• When a field in the request is deprecated, the x-volterra-request-fields-deprecated header is sent in the response.
• When a field in the response is deprecated, the x-volterra-response-fields-deprecated header is sent in the response.

Note: For the field deprecation, the header values are comma-separated-value of field-paths.

References

• Credentials
• API Specification