How to establish an API connection VMware Cloud Director
search cancel

How to establish an API connection VMware Cloud Director

book

Article ID: 320526

calendar_today

Updated On:

Products

VMware Cloud Director

Issue/Introduction

How to establish a connection to VMware Cloud Director.

Environment

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

Resolution

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.


Additional Information

OpenAPI Documention for Sessions

  • https://developer.broadcom.com/xapis/vmware-cloud-director-openapi/39.0/sessions/

PowerCLI Cloud Director Cmdlet Reference Guide

  • https://developer.broadcom.com/powercli/latest/products/vmwareclouddirector/



Powered by Wolken Software