VeloCloud SD-WAN Orchestration API v2

VeloCloud SD-WAN Orchestration API v2

Introduction

VMware SD-WAN Orchestrator release 4.2.0 introduced a new SD-WAN Orchestration REST API, informally referred to as “APIv2.” The API currently supports:

  • Monitoring of Customer SD-WAN deployments (roughly the same feature set that is available via the web UI's Customer -> Monitoring pane) - Min VCO version `4.2.0`
  • Configuration of Edge device settings (both via profiles and Edge-specific overrides) - Min VCO version `5.0.0.0`
  • Configuration of Edge business policy settings (both via profiles and Edge-specific overrides) - Min VCO version `5.0.0.0`

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)

Getting Started

Accessing the API

On Orchestrators running software version 5.0.0.0 or newer, the API is accessible over HTTPS via the `/api/sdwan/v2` URL base path. For all earlier Orchestrator software releases, the `/sdwan` base path must be used. While newer Orchestrator releases currently still attempt to honor API requests to the `/sdwan` base path (by issuing HTTP 308 redirects to the corresponding `/api/sdwan/v2` route), the `/sdwan` base path is considered to be deprecated as of the 5.0.0.0 release. Unless otherwise noted, readers should interpret all URL paths that appear in this document as relative paths, to which the `/api/sdwan/v2` 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 `/api/sdwan/v2/enterprises` endpoint.

Errors

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 `message` and `developerMessage` strings are subject to change at any time; clients should not make any assumptions about the content of these strings.

API Polling Frequency

For stats APIs like link stats, flow stats, health stats, etc. we don't recommend polling any more frequently than once every 10 minutes, as various factors (time skew, processing latency, quirks in the query logic) can cause statistics to appear to be missing over shorter timeframes. Events APIs should be called max once per minute.

Common Parameters

Customer LogicalId

A Customer logicalId, also known as `enterpriseLogicalId` in API terminology, is an important path parameter required for any API request related to a specific Customer and its resources. Currently, APIv2 doesn't support fetching a Customer logicalId from its `id`, or equivalently `enterpriseId`. One needs to call APIv1, the VCO Portal API, to fetch the Customer logicalId using its `id` before sending any request to APIv2 that requires `enterpriseLogicalId`. The process to determine a Customer logicalId is described below:

  • Step 1: Determine the Customer `id` (or `enterpriseId`) from URL path. On any of the Customer pages, check the URL path in the browser's URL address bar and it should end with `/customer/ ` where ` ` is the place you find your Customer id, represented as an integer.
  • Step 2: Make an HTTP POST call to `/enterprise/getEnterprise` in APIv1. Now that you have your Customer id, you are ready to make an HTTP POST call to the `/enterprise/getEnterprise` endpoint in the VCO Portal API to fetch your Customer logicalId using your Customer id. See VeloCloud Orchestrator API for more details regarding how to send requests to and interpret responses from the VCO Portal API.

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

Pagination

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.). Alongside a `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/ /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: `GET /enterprises/ /edges?nextPageLink= `.