VMware SD-WAN Orchestrator API v1

VMware SD-WAN Orchestrator API v1

The VeloCloud Orchestrator (VCO) powers the management plane in the VMware SD-WAN solution. It offers a broad range of configuration, monitoring and troubleshooting functionality to service providers and enterprises alike. The principal web service with which users interact in order to exercise this functionality is called the VCO Portal.

The VCO Portal

The VCO Portal allows network administrators (or scripts and applications acting on their behalf) to manage network and device configuration and query current or historical network and device state. API clients may interact with the Portal via a JSON-RPC interface or a REST-like interface. It is possible to invoke all of the methods described in this document using either interface; there is no Portal functionality for which access is constrained exclusively to either JSON-RPC clients or REST-like ones.

Both interfaces accept exclusively HTTP POST requests. Both also expect that request bodies, when present, are JSON-formatted -- consistent with RFC 2616, clients are furthermore expected to formally assert where this is the case using the Content-Type request header, e.g. Content-Type: application/json.

JSON-RPC Interface

The JSON-RPC API accepts calls via the /portal URL path (e.g. vco.velocloud.net/portal). Consistent with v2.0 of the JSON-RPC specification, the API expects JSON-encoded request payloads that consist of a method name (method), a parameters object (params), a user-specified unique request identifier (id, by convention an integer such as a millisecond-precision epoch timestamp), and a JSON-RPC specification version identifier (jsonrpc). The VCO supports only the 2.0 iteration of the JSON-RPC specification, and so the value of the jsonrpc parameter should always be the string "2.0". A sample request follows:

curl --header 'Content-Type: application/json' --data '{"jsonrpc":"2.0","method":"event/getEnterpriseEvents","params":{"enterpriseId":1},"id":1}' --cookie cookies.txt -X POST https://vco.velocloud.net/portal/

REST-like Interface

The REST-like interface eliminates some of the protocol "overhead" imposed by the JSON-RPC interface, and may feel more familiar to those familiar with URL-based REST semantics. It also offers a greater degree of interoperability with a range of client-side tools designed for use with traditional REST APIs. The interface is accessible via the /portal/rest/ base path. In processing REST-like requests, the VCO parses the method name from the portion of the URL path that follows the base path. The request body need contain only the method parameters, e.g.:

curl --header 'Content-Type: application/json' --data '{"enterpriseId":1}' --cookie cookies.txt -X POST https://vco.velocloud.net/portal/rest/event/getEnterpriseEvents

Authentication

API Tokens

As of the 3.4.0 release the Orchestrator supports a token-based authentication scheme based on the HTTP Authorization header, in addition to the cookie-based authentication scheme it has historically supported. Where privileges allow, users may provision and download API tokens via the "Account" page on the Orchestrator Web UI. API tokens may be downloaded only once, and should be treated as sensitive, just as you would treat a password. API tokens are typically longer-lived than session cookies, but clients may refresh them when required using either the Orchestrator Web UI or the underlying token management API methods.

Tokens are passed to the server in an HTTP Authorization header. For example:

curl --header 'Content-Type: application/json' --header 'Authorization: Token <token>' --data '{"enterpriseId":1}' -X POST https://vco.velocloud.net/portal/rest/event/getEnterpriseEvents

Cookie-Based Authentication

The VCO API supports cookie-based authentication. Most programming languages and HTTP client applications expose libraries or options that facilitate the management and use of session cookies, which clients are free to leverage in working with the VCO (e.g. curl exposes the --cookie-jar and --cookie options, Python's requests library exposes a Session interface, etc.). Numerous code samples, wherein authentication is demonstrated in a variety of programming languages, are available via VMware Sample Exchange.

Clients initiate sessions by invoking either the login/enterpriseLogin or the login/operatorLogin method, depending on the user type associated with the client's credentials (Partner and Customer Admins should use the former method, and Operator Admins the latter). In the event of a successful authentication call, the API responds with an HTTP 200 status code and embeds a velocloud.session cookie in a Set-Cookie response header. When authentication is unsuccessful, the API responds with an HTTP 302 status code and includes a short message elaborating on the failure in a velocloud.message cookie. A sample authentication call is demonstrated with the curl command-line utility below (response truncated for brevity):

curl --cookie-jar /tmp/cookie.txt -i -X POST https://vco.velocloud.net/portal/rest/login/enterpriseLogin --data '{"username":"[email protected]","password":"'$SECRET'"}'
< HTTP/1.1 200 OK
< Set-Cookie: velocloud.session=<token>; <attributes>

Once a client has successfully retrieved a session cookie, it may begin to make API calls to API methods that require authentication by embedding the velocloud.session cookie in a Cookie request header (programming languages and other client utilities typically provide interfaces that simplify this).

Session cookies typically expire after a period of 24 hours (though liftetimes are configurable and may vary across VCO deployments). It is considered best practice to invalidate cookies whenever they are no longer required by initiating a call to the logout API method:

curl --cookie /tmp/cookie.txt -X POST https://vco.velocloud.net/portal/rest/logout

Data Model & Terminology

The terminology of the VCO API schema doesn't always align with the terminology of the Web Console. Consider this a "cheat sheat" to aid in interpreting API constructs:

  • Enterprise: Customer
  • Enterprise Proxy: Partner
  • Network: The Network construct encapsulates all resources in the VCO Operator scope. In typical environments, each VCO has exactly one Network (to which all Partners and Customers belong), and the ID of that Network is 1. Methods in the /network namespace are generally reserved exclusively for Operator use.
  • Configuration: Device configurations are modeled in the API schema as a composition of "Configuration" entities. There are effectively three distinct types of Configurations: Operator Profiles (also referred to as "Software Images"), Customers Profiles (referred to in the API schema as "Enterprise Configurations"), and Edge-Specific Profiles.
  • Configuration Module: Each configuration is composed of a set of modules (e.g. deviceSettings, QOS, firewall, controlPlane, etc.), wherein the actual configuration data resides. In the current version of the API, configuration changes must always be applied at the module level (i.e. via calls to the configuration/updateConfigurationModule API method). Partial updates on specific sections of Configuration Module data are not (yet) supported.
  • Refs: refs are associations between a Network Service (e.g. DNS providers, authentication services, VPN hubs, etc.) and a Configuration (more precisely, a Configuration Module). They should generally be treated as read-only.

Common Parameters

A few parameters appear repeatedly throughout the API schema:

enterpriseId

The Portal API enforces that an enterpriseId parameter is required on any request initiated by an Operator or Partner Administrator that accesses, or operates upon, a Customer-managed resource (e.g. Edges, Profiles, network services). enterpriseId is never required for API calls initiated by Customer Administrators (in such cases it is inferred based on the user's credential).

enterpriseProxyId

Similar to the enterpriseId parameter, the Portal API enforces that an enterpriseProxyId parameter is required on any request initiated by an Operator Administrator that accesses, or operates upon, a Partner-managed resource (e.g. Partner Events, Partner Gateway Pools, etc.). enterpriseProxyId is never required for API calls initiated by Partner Administrators (in such cases it is inferred based on the user's credential).

networkId

Some API methods accept a networkId parameter, which determines the Network context in which a request is processed. Partner and Customer Administrators need never use this parameter, as those user types exist within the context of a single Network which is trivially inferred by the VCO. Meanwhile, Operator Administrators need only specify a value for this parameter in highly-atypical multi-Network VCO deployments (e.g. test environments).

with

Many "fetch" API methods support a with parameter, which allows the user to optionally resolve related entities. recentLinks is a special instance of one such option that is supported by methods that fetch Edges, which will cause the API to resolve WAN links for which activity has been recorded in the last 24 hours. This should generally be preferred to the links option on methods where it is supported.

interval

Many methods, such as those that query events or volumetric flow data, support a query interval. The default query interval, inferred by the server when none is otherwise specified, is the most recent 12 hour period.

The VCO exposes time series data (e.g. device system health metrics such as CPU and memory usage, network metrics such as latency/jitter/loss, volumetric traffic flow data) via various API methods that accept query intervals. By default, Edges and Gateways report new statistics to the Orchestrator every five minutes. Due to various factors (clock drift, network jitter, server-side processing delays), statistics associated with a given interval beginning at time t are often not reflected in API output until time t + 10 minutes. As such, we do not recommend using query intervals smaller than 10 minutes in time for these methods.

Datetimes

The Orchestrator API uses UTC time universally. Whenever a method request schema calls for a datetime value, and whenever a response includes a datetime value, the timezone should be inferred to be UTC.

The VCO accepts the following datetime formats:

  • 13-digit millisecond-precision epoch timestamps (e.g. 1500000000000)
  • Datetime strings formatted consistently with RFC 3339. (e.g. "2017-01-01T00:00:00.000Z")

Rate Limits

The VCO makes use of a rate-limiting mechanism to ensure an equitable allocation of server resources among API clients and safeguard overall system stability. The VCO supports two kinds of API rate limits:

  • Concurrency limits govern the maximum number of requests that the server processes on behalf of a client or tenant at any given moment.
  • Leaky-bucket limits prevent bursty client activity by limiting the number of requests processed by the server on behalf of a particular client or tenant within a short time period (5 seconds, by default).

Rate limiting policies are configurable at the discretion of the VCO Operator, and as such can vary from one environment to the next. Questions regarding the policies applicable to your environment should be directed to your VCO Operator.

When an API client is rate limited, it incurs a "penalty" whereby the server refuses to process new requests on its behalf for a brief period of time (5 seconds, by default). During this time, the server issues responses bearing the HTTP 429 status code (Too Many Requests) to the rate-limited client.

Developers are advised to take the following steps to (1) avoid triggering defensive rate limiter responses, and (2) mitigate the impact of rate limiter penalties.

  • Handle HTTP 429 responses by implementing a constant-time "backoff" (i.e. wait 5 seconds) before attempting another request.
  • Limit the number of requests in flight at any given time to no more than a handful.
  • Limit polling frequency based on the rate at which source data is refreshed on the server (5 minutes for device statistics, 30s for most other data points).
  • When a use case requires querying multiple sites, prefer "aggregate" query methods (e.g. monitoring/getAggregateEdgeLinkMetrics) to those that query one site at a time (e.g. metrics/getEdgeLinkMetrics), wherever possible.

Backward Compatibility

We endeavor not to introduce backward-incompatible changes in the API unless we consider such a change to be essential to the security or stability of the product. We view the following classes of changes as backward-compatible:

  • Changes that introduce new API methods
  • Changes that introduce new optional request parameters
  • Changes that introduce new response parameters
  • Changes that add support for new values to existing enumerations (i.e. properties that have a discrete range of possible values)
  • Changes to the format of opaque (i.e. server-generated) strings (e.g. entity identifiers)
  • Changes to API error messages
  • Changes to Event messages and details
  • Changes to the content of alert messages (except where that content is specifically dictated by the user, e.g. for Webhooks)