VeloCloud SASE Platform APIs

Getting Started with VMware SASE Platform APIs

The VMware SASE Platform exposes a suite of RESTful web services that VMware partners and customers may use to automate network monitoring, management and troubleshooting tasks. This page provides a brief overview of some of the fundamental features of the API architecture on which these services are based.

Authentication

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 as described in the VMware SASE product documentation. 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.

Errors

The API’s usage of HTTP status codes is based on the guidance prescribed in RFC 7231. Specifically:

  1. A 2xx response indicates that a request was “successfully received, understood, and accepted.”
  2. 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.
  3. 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.

Common Parameters

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/<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: GET /enterprises/<enterpriseId>/edges?nextPageLink=<nextPageToken>.

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 operations
  • 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 set 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