Introduction

With IBM Cloud™ for VMware Solutions Shared, you can quickly and seamlessly migrate or deploy VMware workloads to the cloud on top of your professionally-managed VMware infrastructure. IBM provides a self-service VMware cloud computing platform with vCloud Director running on IBM Cloud. This infrastructure-as-a-service (IaaS) pay-as-you-go offering allows you to consume vCPU, storage, RAM, networking, backup services, and operating system license rentals, as needed.

By using the IBM Cloud for VMware Solutions Shared REST API you acknowledge that you have read and accepted the following third-party agreement:

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 type response indicates success, a 400 type response indicates a failure, and a 500 type response indicates an internal system error.

HTTP error code Description Recovery
200 Success The request was successful.
202 Success The request was submitted successfully.
400 Bad request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request because of missing or bad authentication token.
403 Forbidden The supplied authentication is not authorized to make this request. Contact the account owner to check your permissions.
409 Conflict The request cannot be completed because of a conflict with the current state of the target resource.
500 Internal server error Your request cannot be processed. Wait a few minutes and try again. If the error persists, contact IBM Support.

When an API operation fails, detailed information about the failure is provided in the response. In addition, in every response there is a header named x-global-transaction-id, which is a unique identifier for the API operation. When contacting IBM Support about API operation failures, you can provide the x-global-transaction-id for better debugging.

Authentication

To work with the API, you must add an IBM Cloud IAM access token in the API request authentication header:

-H 'Authorization: Bearer <IAM_TOKEN>'

You can retrieve an IBM Cloud IAM access token by using the IBM Cloud CLI, or by creating an API key and then exchanging the API key for an IBM Cloud IAM access token. For more information, see Getting an IAM token.

Methods

Get the list of virtual data center tenant access points

Virtual datacenter access points are associated with all virtual datacenter instances in the same region and define the URL for access to the vCloud Director web UI and for API calls.

GET /locations
Request

Custom Headers

  • curl -X GET \
      https://vcd-api.vmware-solutions.cloud.ibm.com/v1/locations \
      -H 'Content-Type:application/json'
Response

Status Code

  • OK

Example responses
  • [
      {
        "enabled": true,
        "url": "https://sao01.director.com/tenant/UXN9G6",
        "value": "sao01"
      },
      {
        "enabled": false,
        "url": "https://dal10.director.com/tenant/UXN9G6",
        "value": "dal10"
      }
    ]

Get the list of global datacenter locations where VMware virtual datacenters can be deployed

GET /locations/catalog
Request

Custom Headers

  • curl -X GET \
      https://vcd-api.vmware-solutions.cloud.ibm.com/v1/locations/catalog \
      -H 'Content-Type:application/json'
Response

Status Code

  • OK

Example responses
  • [
      {
        "region": "nasouth",
        "value": "dal10"
      },
      {
        "region": "southamerica",
        "value": "sao01"
      }
    ]

Reset the vCloud Director organization password for the admin user

The admin credentials are used for all VMware Solutions Shared and Dedicated instances located in a region. If you change the password of the admin account, the password will be changed for all instances that are in that region.

PUT /locations/{location}/password
Request

Custom Headers

Path Parameters

  • curl -X PUT \
      https://vcd-api.vmware-solutions.cloud.ibm.com/v1/locations/<location_value>/password \
      -H 'Content-Type:application/json'
Response

Status Code

  • OK

Example responses

Get the list of services included with virtual datacenters

Services add capabilities to virtual datacenters such as backup, compliance controls, and workload migration. The use of services can have additional costs.

GET /services/catalog
Request

Custom Headers

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Interal Server Error

Example responses
  • {
      "service1": {
        "display_name": "Service 1, v0.0.1",
        "service_category": "Disaster Recovery"
      },
      "service2": {
        "display_name": "Service 2",
        "service_category": "A Service2 Manager"
      },
      "service3": {
        "display_name": "Service 3, v7.1",
        "service_category": "Service3 Storage"
      }
    }

Return virtual datacenter service details.

Services add capabilities to virtual datacenters such as backup, compliance controls, and workload migration. The use of services can have additional costs.

GET /vdcs/{vdc_uuid}/services
Request

Custom Headers

Path Parameters

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Forbidden

  • Not Found

  • Interal Server Error

  • Service unavailable

Example responses
  • {
      "service1": {
        "display_name": "Service1",
        "self_service_url": "https://service1.vmware-solutions.cloud.ibm.com:2222/123456",
        "status": "Creating",
        "uri": "/v1/vdcs/vdc_uuid1/services/vdc_service1"
      },
      "service2": {
        "display_name": "Service2",
        "self_service_url": "https://service1.vmware-solutions.cloud.ibm.com:2222/123456",
        "status": "ReadyToUse",
        "uri": "/v1/vdcs/vdc_uuid1/services/vdc_service2"
      }
    }

Return details of the specified virtual datacenter service.

Services add capabilities to virtual datacenters such as backup, compliance controls, and workload migration. The use of services can have additional costs.

GET /vdcs/{vdc_uuid}/services/{service_id}
Request

Custom Headers

Path Parameters

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Forbidden

  • Not Found

  • Interal Server Error

  • Service unavailable

Example responses
  • {
      "display_name": "Service2",
      "self_service_url": "https://service1.vmware-solutions.cloud.ibm.com:2222/123456",
      "status": "ReadyToUse",
      "uri": "/v1/vdcs/vdc_uuid1/services/vdc_service2"
    }

List all virtual datacenter instances

GET /vdcs
Request

Custom Headers

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

Example responses
  • [
      {
        "allocation_model": "ondemand",
        "cpu": 10,
        "created_by": "a-user-name",
        "created_time": 1507646782,
        "crn": "crn:v1:public:vmware-solutions:global:a/my-account-8888:448083af-a249-4271-96bf-9e407ca9bb0c::",
        "instance_type": "vdc",
        "location_url": "https://dal10dir01.vmware-solutions.cloud.ibm.com",
        "location": "dal10",
        "name": "vdctest1",
        "ram": 256,
        "ordered_by": "a-user-name",
        "ordered_time": 1507646782,
        "public_ip": [
          "169.0.0.1",
          "169.0.0.2",
          "169.0.0.3",
          "169.0.0.4",
          "169.0.0.5"
        ],
        "status": "ReadyToUse",
        "uuid": "448083af-a249-4271-96bf-9e407ca9bb0c"
      }
    ]

Create a new virtual datacenter

POST /vdcs
Request

Custom Headers

Response

Status Code

  • Accepted

  • Bad Request

  • Unauthorized

  • Service unavailable

Example responses
  • {
      "allocation_model": "ondemand",
      "cpu": 10,
      "created_by": "a-user-name",
      "created_time": 1507646782,
      "crn": "crn:v1:public:vmware-solutions:global:a/my-account-8888:448083af-a249-4271-96bf-9e407ca9bb0c::",
      "instance_type": "vdc",
      "location_url": "https://dal10dir01.vmware-solutions.cloud.ibm.com",
      "location": "dal10",
      "name": "vdctest1",
      "ram": 256,
      "ordered_by": "a-user-name",
      "ordered_time": 1507646782,
      "public_ip": [],
      "status": "Creating",
      "uuid": "448083af-a249-4271-96bf-9e407ca9bb0c"
    }
  • [
      {
        "name": [
          "Name must be unique. my-vdc-name is already in use."
        ],
        "cpu": [
          "vCPU must be in the range of 1-10 cores"
        ],
        "ram": [
          "RAM must be in the range of 1-80 GB"
        ]
      }
    ]

Retrieve the detailed information of a VMware virutal datacenter

GET /vdcs/{vdc_uuid}
Request

Custom Headers

Path Parameters

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Forbidden

  • Not Found

Example responses
  • {
      "allocation_model": "ondemand",
      "cpu": 10,
      "created_by": "a-user-name",
      "created_time": 1507646782,
      "crn": "crn:v1:public:vmware-solutions:global:a/my-account-8888:448083af-a249-4271-96bf-9e407ca9bb0c::",
      "instance_type": "vdc",
      "location_url": "https://dal10dir01.vmware-solutions.cloud.ibm.com",
      "location": "dal10",
      "name": "vdctest1",
      "ram": 256,
      "ordered_by": "a-user-name",
      "ordered_time": 1507646782,
      "public_ip": [
        "169.0.0.1",
        "169.0.0.2",
        "169.0.0.3",
        "169.0.0.4",
        "169.0.0.5"
      ],
      "status": "ReadyToUse",
      "uuid": "448083af-a249-4271-96bf-9e407ca9bb0c"
    }

Change a virtual datacenter's vCPU and RAM configuration

PUT /vdcs/{vdc_uuid}
Request

Custom Headers

Path Parameters

Response

Status Code

  • Accepted

  • Bad Request

  • Unauthorized

  • Forbidden

  • Not Found

  • Service unavailable

No Sample Response

This method does not specify any sample responses.

Delete a virtual datacenter

DELETE /vdcs/{vdc_uuid}
Request

Custom Headers

Path Parameters

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Forbidden

  • Not Found

  • Service unavailable

No Sample Response

This method does not specify any sample responses.