SD-WAN REST API v2 latestOpenAPI Specification Download
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. The API currently supports monitoring of Customer deployments (roughly the same feature set that is available via the web UI’s Customer -> Monitoring pane). Configuration APIs are under active development for APIv2 and are available as part of APIv1 on https://code.vmware.com/apis/1115/velocloud-sdwan-vco-api
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
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.
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.