The VMware Cloud Director API for NSX is a proxy API that enables VMware Cloud Director 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 VMware Cloud 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 VMware Cloud Director API for NSX.

Relationship to the NSX API

The VMware Cloud 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, with related examples documented in the NSX vSphere API Guide, can be used by callers of the VMware Cloud Director API for NSX with a few modifications and some additional constraints.

Relationship to the VMware Cloud Director API

The VMware Cloud Director API for NSX is not part of the VMware Cloud Director API. It uses a proxy facility to allow clients that have authenticated to the VMware Cloud Director API to make NSX API requests through the VMware Cloud 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 through the VMware Cloud Director OpenAPI. For information about VMware Cloud Director OpenAPI, see Getting Started with vCloud OpenAPI at https://developer.vmware.com/.

Multi-Tenant Support

The NSX API addresses NSX objects in a global scope like that of a VMware® vCenter™ data center. The NSX Proxy API addresses NSX objects within the scope of a VMware Cloud 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 VMware Cloud Director API for NSX uses the identifier that VMware Cloud 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 VMware Cloud 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 VMware Cloud Director organization or VDC UUID in the request to limit access to tenants with rights to the VMware Cloud Director object.

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

Security

HTTP communications between a VMware Cloud Director 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 VMware Cloud 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 VMware Cloud 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 64 KB 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 VMware Cloud Director 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.