About the vCloud Director API for NSX

The vCloud Director API for NSX is a proxy API that enables vCloud API clients to make requests to the NSX API.

Use this document as a supplement to the NSX vSphere API Guide (NSX version 6.3 or later). This document lists the subset of NSX API requests supported by the vCloud Director API for NSX and provides information about differences between those requests as they are described in the NSX API documentation and how you must make them when using the vCloud Director API for NSX.

Relationship to the NSX API

The vCloud Director API for NSX supports a subset of the operations and objects defined in the NSX vSphere API Guide. The API supports NSX 6.3 and 6.4. You can download the NSX vSphere API Guide from https://pubs.vmware.com/nsx-63/topic/com.vmware.ICbase/PDF/nsx_63_api.pdf (NSX 6.3) or https://docs.vmware.com/en/VMware-NSX-for-vSphere/6.4/nsx_64_api.pdf (NSX 6.4). Requests listed in this document, along with related examples documented in the NSX vSphere API Guide, can be used by callers of the vCloud Director API for NSX with a few modifications and some additional constraints.

Relationship to the vCloud API

The vCloud Director API for NSX is not part of the vCloud API. It uses a proxy facility to allow clients that have authenticated to the vCloud API to make NSX API requests through the vCloud Director secure public URL with a network suffix. Examples in this document represent this URL as https://vcloud.example.com/network.

Note: The cross-virtual data center networking feature is available via the vCloud OpenAPI. For information about vCloud OpenAPI, see Getting Started with vCloud OpenAPI at https://code.vmware.com.

Multi-Tenant Support

The NSX API is designed to address NSX objects in a global scope like that of a VMware® vCenter™ datacenter. The NSX Proxy API is designed to address NSX objects within the scope of a vCloud Director tenant organization.

Where the NSX API uses internal edge identifiers such as edge-1 (typically shown as edgeId in the NSX vSphere API Guide) to identify an edge, the vCloud Director API for NSX uses the identifier that vCloud Director assigns to the edge. This is a unique identifier in the form of a UUID, as defined by RFC 4122. Use of this identifier allows the API to restrict access to an edge to members of the organization that owns the edge. Organization members' access to an edge is also governed by their role in the organization and the rights associated with that role. The vCloud Director API for NSX uses this edge UUID only to identify the edge, locate the NSX Manager responsible for the edge, and retrieve its internal NSX edge id, which it uses in subsequent NSX API operations on the edge.

Operations on other NSX objects such as certificates and grouping objects typically require a vCloud Director organization or VDC UUID in the request to limit access to tenants with rights to the vCloud Director object.

vCloud Director system administrators can view or update all edges in the system.

Security

HTTP communications between a vCloud API client and server are secured with SSL. API clients must also complete a login request to receive an authorization token that must be included in all subsequent requests.

Request Headers

The following HTTP headers are typically included in requests:

Accept

All requests must include an HTTP Accept header that designates the vCloud Director API for NSX version that the client is using.

Accept: application/*+xml;version=api-version

For example, the following header indicates that the request is from a vCloud Director API for NSX version 29.0 client.

Accept: application/*+xml;version=29.0

Accept-Encoding

By default, the system returns response content as uncompressed XML. Compressing the response can improve performance, especially when the response is large and network bandwidth is a factor. (Requests cannot be compressed.) To request a response to be returned as compressed XML, include the following header:

Accept-Encoding: gzip

The response is encoded using gzip encoding as described in RFC 1952, and includes the following header:

Content-Encoding: gzip

In the default configuration, responses smaller than 64KB are never compressed.

Accept-Language

Message strings in ErrorType responses are localized. To specify the language desired in responses, use the Accept-Language request header. To request a response with message strings localized to French, use the following header:

Accept-Language: fr

Authorization

All requests to create a vCloud API session must include an Authorization header of the form prescribed by the identity provider that your organization uses. See the vCloud API Programming Guide for Service Providers.

Content-Type

Requests that include a body must include the following HTTP Content-Type header.

Content-type: application/xml

x-vcloud-authorization

This header, which is returned with the Session response after a successful log-in, must be included in all subsequent requests from clients that authenticate to the integrated identity provider or the SAML identity provider. See the vCloud API Programming Guide for Service Providers.

X-VMWARE-VCLOUD-CLIENT-REQUEST-ID

The value of this header is used to build a request ID returned in the value of the X-VMWARE-VCLOUD-REQUEST-ID header. The value of this header cannot contain more than 128 characters drawn from the set of letters, numbers, and the hyphen (-). Values with invalid characters are ignored. Values with more than 128 characters are truncated.