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 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`.
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/ 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 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\":\"admin@velocloud.net\",\"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
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:
A few parameters appear repeatedly throughout the API schema:
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).
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).
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.
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.
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: