VMware SD-WAN Orchestration REST API v2 2021-02-18
The 4.2.0 VMware SD-WAN Orchestrator release introduces a new SD-WAN Orchestration REST API, informally referred to as “APIv2” because it is intended to gradually replace the VCO Portal API (“v1”) as the primary interface supported for Partner and Customer development. Designed with extensive input from users of the Portal API, APIv2 offers an improved developer experience to new and experienced users alike.
The API embraces the REST architectural style and draws on design conventions and best practices that are well-established within VMware and beyond, among these:
- The usage of standard HTTP methods to denote how API operations behave
- The usage of a range of standard HTTP status codes in a manner consistent with the definitions specified in RFC 7231 (e.g. 201 is used to indicate that a resource was successfully created, 400 is used when the server detects a request syntax error, etc.)
- The usage of hyperlinks to represent relations among API resources and facilitate navigation of the API (e.g. Customer Edges are represented with a URL path like
/enterprises/a980c178-6c32-45ca-aaf9-1c74d441eb69/edges/ca607949-0263-4bc7-afb0-d37a165da82c, and any given Edge may be fetched via a simple HTTP GET request to that path)
Accessing the API
The API is accessible over HTTPS via the
/sdwan URL base path on Orchestrators running software versioned 4.2.0 or later. Unless otherwise noted, readers should interpret all URL paths that appear in this document as relative paths, to which the
/sdwan base path must be prepended in order to produce complete, valid URL paths. For example, to fetch a collection of Customers, an Operator Admin would make an HTTP GET call to the
An API token is required to access the API. Users may generate and download API tokens via the Orchestrator Web UI by navigating to the “Account” page. Users should treat API tokens as highly sensitive, just as they would treat their Orchestrator password.
The API server looks for API tokens on incoming requests in an HTTP Authorization header which specifies the
Token authentication scheme. That is to say, a well-formed Authorization header containing an API token looks like:
Authorization: Token <token>
The Orchestrator executes all API operations as the user to whom the client’s API token belongs (i.e. the client is afforded precisely the same permissions as the user that downloaded that token).
API token lifetimes are configurable at the discretion of users (to an extent, as permitted by the VCO Operator). Tokens may be refreshed via the UI or the VCO Portal API.
Requests and Response Data
For those API operations that accept a request body (i.e. for PATCH, PUT, and some POST operations) the API accepts exclusively JSON data. Consistent with RFC 2616, the API server expects clients to formally assert when a request body does contain JSON data using the Content-Type request header, i.e. Content-Type: application/json. Many client utilities and libraries do this automatically.
Response bodies are, likewise, JSON-encoded.
Per RFC 8259, the API expects all JSON request bodies to be encoded using the UTF-8 character set (this does not typically require any special configuration on the part of the client). Similarly, the API encodes all JSON data in its responses using UTF-8.
The API’s usage of HTTP status codes is based on the guidance prescribed in RFC 7231. Specifically:
- A 2xx response indicates that a request was “successfully received, understood, and accepted.”
- A 4xx response indicates that the server is unable to process a request, which is typically due to bad request syntax (e.g. non-JSON data, invalid parameter types) or validation issues generated by business logic.
- A 5xx response is indicative of an unexpected server error, which may stem from a code or performance issue or a transient lapse in application or infrastructure availability.
The API does not use 1xx or 3xx status codes.
All error responses that originate from the API include a JSON response body containing the following attributes:
code: A short string that uniquely identifies the error
message: A brief, user-friendly message elaborating on the error that occurred
developerMessage: A technical error message intended to help the developer of the client script or application to better understand the error
errors: A detailed list of syntax validation errors, if any
Note that the content of the
developerMessage strings are subject to change at any time; clients should not make any assumptions about the content of these strings.
HTTP GET operations that query resource collections of indeterminate size produce paginated result sets. This helps ensure that the API user experience does not degrade as a user’s resource footprint expands across various dimensions (e.g. number of Edges deployed, number of Customer events generated, etc.).
data array which contains a (possibly truncated) result set, paginated responses include a
metaData object. In the event that a query matches a result set that is larger than the server-enforced maximum size (or a user-specified
limit, if one was provided), a
nextPageLink token is included in the response
metaData object. That token may be passed to the server in a subsequent GET request as a query parameter called
nextPageLink in order to fetch the next page in the result set.
For example, suppose a Customer has 3000 Edges and an API user with access to that Customer makes an initial query to
GET /enterprises/<enterpriseId>/edges. We expect that this query will “match” all 3000 Customer Edges. The server, however, enforces a maximum result set size of 2048, so it produces a
data array containing 2048 Edges, and a
metaData object alongside that array which includes a
nextPageLink token. The user would fetch the next page in the result set by making a request to:
Graph Traversal (Experimental)
All HTTP GET operations support a query parameter named include, which may be used to dynamically resolve “nested” resource attributes beyond the
_href pointer that is produced by default for all linked resources. The server treats the value of the include parameter as a comma-separated list of paths referring to nested parameters. e.g. If a user were to submit a request to
GET /enterprises/<enterpriseId>/edges, that user could instruct the server to resolve geographic site coordinates for each Edge using the HTTP query option
include=site.lat,site.lon). The server also supports the use of a special wildcard operator (
*) in include expressions, which may be used to resolve all attributes associated with a particular linked resource (e.g.
include=site.* can be used to instruct the server to produce all attributes associated with an Edge site).
This feature is considered experimental at this time; it is not yet supported for all linked resources, and the server does not support resolution of doubly-nested (or triply-nested, etc.) attributes.