The VMware Cloud Director API for NSX-T Data Center is a proxy API that enables VMware Cloud Director API clients to make requests to the NSX-T Data Center API.

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

Relationship to the NSX-T Data Center API

The VMware Cloud Director API for NSX-T Data Center supports a subset of the operations and objects defined in the NSX vSphere API Guide. For information about the NSX-T Data Center versions that VMware Cloud Director API support, see VMware Product Interoperability Matrices. To see the NSX-T Data Center documentation, visit https://docs.vmware.com/en/VMware-NSX/index.html. 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-T Data Center with a few modifications and some additional constraints.

Relationship to the VMware Cloud Director API

The VMware Cloud Director API for NSX-T Data Center 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-T Data Center 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-T Data Center API addresses NSX-T Data Center objects in a global scope like that of a VMware® vCenter™ data center. The NSX-T Data Center Proxy API addresses NSX-T Data Center objects within the scope of a VMware Cloud Director tenant organization.

Where the NSX-T Data Center 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-T Data Center 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-T Data Center uses this edge UUID only to identify the edge, locate the NSX-T Data Center Manager responsible for the edge, and retrieve its internal NSX-T Data Center edge ID, which it uses in subsequent NSX-T Data Center API operations on the edge.

Operations on other NSX-T Data Center 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-T Data Center 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-T Data Center 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.