How to establish a connection to VMware Cloud Director.

VMware Cloud Director for Service Provider 9.x
VMware Cloud Director for Service Provider 8.x

There are many methods by which a User can connect to the Cloud Director API.
Each method is in essence a REST Client some of which have layers to hide some of the fundamental/basic mechanics surrounding connection.

• cURL
• Postman
• API Explorer (embedded in the Cloud Director UI)

Regardless of the Client, the requirements for each will be the same

1. VCD_FQDN
2. Valid Credentials
3. Valid REST Headers
4. Valid API Version
5. Login Session
6. Token for Subsequent API Calls

• VCD_FQDN
  • This is the FQDN by which your Cloud Director instance is accessible.
  • https://example.vmware.com/provider
  • example.vmware.com is the FQDN.
• Valid Credentials
  • Depending on the endpoint you are logging into, you will need to specify the Tenant Organization
    • administrator@system would be the username for the default administrator
• Valid REST Headers
  • These are the headers you specify so that the Cloud Director knows what type information to expect, or what type of information you want in return.
    • Accept - What type of information do you want from the Server.
    • Content-Type - What type of information are you planning on sending.
• Valid API Version
  • For each Major Version of Cloud Director, there is a corresponding API Version.
  • Like with the Major Version of the Product, an API Version will also go end of life.
  • Along with a Version being active, there are also some functions that are only possible on later Versions of the API.
    • As of 10.4, 37.0 is the latest, non-beta version of the API
• Login Session
  • Like with the UI, each User will need to authenticate with the API.
  • Once authenticated, you are presented with a Token which allows you to run API Calls until that Token expires.
• Token for Subsequent API Calls
  • The most common API Token is generated via an API Login Session
  • Starting with 10.3.1, it is possible to create an API Access Token which is beneficial for automation as they do not expire.
  • https://docs.vmware.com/en/VMware-Cloud-Director/10.4/VMware-Cloud-Director-Tenant-Portal-Guide/GUID-A1B3B2FA-7B2C-4EE1-9D1B-188BE703EEDE.html

cURL

This is the one of the most basic REST Clients that will allow you to connect to Cloud Director and run API calls.

Locate and choose a Valid API version.
curl -ksSL -D - -X GET https://$HOSTNAME/api/versions

<VersionInfo deprecated="false">    ## This indicates whether there is a plan to remove or not
        <Version>37.0</Version>       ## 37.0 is the version in this instance

Create a Login Session 
curl -ksSL -D - -X POST https://VCD_FQDN/cloudapi/1.0.0/sessions/provider -H "Accept: application/json;version=37.0" -u "administrator@system:<Password>"

• We are using the Accept Header i.e. communicate to us using JSON and use API Version 37.0.
• /sessions/provider is the provider login endpoint
  • /sessions would be the tenant login endpoint
  • user@tenant is the username format for a tenant login

As part of the output, you will receive a set of Response Headers, one of which will be 

• X-VMWARE-VCLOUD-ACCESS-TOKEN: <Unique String>
  • Unique String is usually several lines long.
  • This is the Token for Subsequent API Calls specified above.
    • Authorization: Bearer <Unique String>

Subsequent API Example - Cross Origin Resource Sharing (Cors) Settings
curl -ks -X GET "https://VCD_FQDN/cloudapi/1.0.0/site/settings/cors?page=1&pageSize=25" -H "Accept: application/json;version=37.0" -H "Authorization: Bearer <Unique String>" 

• Note we no longer provide the Credentials.
• If you needed to modify data, you would use another API Method
  • PUT - Update an existing object
  • POST - Create a new Object
  • DELETE - Delete an existing Object
    • If you are sending data to the Server you would need additional headers such as Content-Type already mentioned.
    • For APIs that use /cloudapi/ such as CORS above, the Content-Type has to be JSON.

If you wish to use any other Rest Client, it is simply a process of identifying where to place the requested information.

• Depending on the Client, they may have the ability to replay or save previously run calls, or in some instances have the ability to simplify the login process.
  • POSTMAN would be a good example for a REST Client which makes the process easier, whilst still exposing the requirements.
  • PowerCLI is a wrapper for API Calls, and as such hides a lot of the basics from the end user, making the process extremely straight forward but it not transferrable to other methods.
    • If you can run cURL or Postman, you will understand what PowerCLI is looking to achieve.
    • Whereas if you have only every run PowerCLI, you may not know what is going on underneath.

OpenAPI Documention for Sessions

• https://vdc-download.vmware.com/vmwb-repository/dcr-public/772aa4c5-7e61-4d80-8432-b8e0d821c969/2747ec83-6aef-4560-b1d1-55ed9adc4e73/vcd-openapi-docs.html#api-Sessions-providerLogin

PowerCLI Cloud Director Cmdlet Reference Guide

• https://developer.vmware.com/docs/powercli/latest/products/vmwareclouddirector/