Create API requests and handle responses

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This document describes how to construct API requests and handle API responses from the VMware Engine API. It covers how to do the following:

• Construct a request body.
• Determine the resource URIs necessary for a request.
• Handle API responses.
• Determine whether an API request succeeded.

This document does not cover how to authenticate with the API. To learn how to authenticate with the API, read Authenticating requests.

Before you begin

• Be familiar with REST APIs.
• Know how to authenticate requests to the VMware Engine API.

Create an API request

The VMware Engine API expects API requests to be in JSON format. To make an API request, make a direct HTTP request by using tools like curl or httplib2. When you make an API request that requires a request body, like a POST, UPDATE, or PATCH request, the request body contains resource properties that you set in the request.

For example, the following curl command makes a POST request to the PrivateCloud resource URI. The request creates a private cloud with the properties defined in the request body. The curl request body is indicated by the -d flag:

curl -X POST "https://vmwareengine.googleapis.com/v1/projects/example-project/locations/europe-west4-a/privateClouds?privateCloudId=example-privatecloud" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
  "networkConfig":{
    "managementCidr": "192.168.1.0/24"
    "vmwareEngineNetwork": "projects/example-project/locations/europe-west4/vmwareEngineNetworks/europe-west4-default",
  },
  "managementCluster":{
    "clusterId": "example-cluster"
    "nodeTypeId": "standard-72",
    "nodeCount": 3,
  },
  "description": "Example description of a private cloud"
}'

Creating resource URIs

In the VMware Engine API, a reference to another Google Cloud resource is given as a resource name. This format applies when you specify a private cloud, a cluster, a VMware Engine network, or any other resource.

For example, you might need to specify a network as part of a peering setup using a relative resource name. To provide the global default network in the the network property, your relative resource name looks something like this:

projects/example-project/network/default

In the preceding example, the specified network is a resource in the example-project project.

When performing list operations, you can also insert a wildcard using a hyphen (-). For example, the following resource name refers to private clouds in all locations of the specified project:

projects/example-project/locations/-/privateClouds

Determine required properties

The VMware Engine API reference documentation describes all of the possible properties you can set for a specific resource. The reference documentation makes a distinction between mutable versus immutable properties (marked by "Output only" in the property description). To determine required properties for an API method, review the documentation specific to the API method and identify properties marked as "Required" in the description.

Handle API responses

If you make a request that changes data, VMware Engine returns an Operation object that you can then poll to get the status of the operations for your request. When the operation is running, the Operation resource looks like the following example:

{
  "name": "projects/example-project/locations/europe-west4-a/operations/operation-1629406175532-5c9efb0499490-22bf8217-c53fd451",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vmwareengine.v1.OperationMetadata",
    "createTime": "2021-08-19T20:49:37.261822386Z",
    "target": "projects/example-project/locations/europe-west4-a/privateClouds/example-privatecloud",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Your request is not complete until the done field of the Operation resource returns as true. This process can take some time depending on the nature of your request. After the done field returns as true, you can check to see if the operation succeeded and whether there were any errors.

For example, the following response indicates that the preceding operation is now complete, and the absence of the error field indicates that the operation succeeded with no errors:

{
  "name": "projects/example-project/locations/europe-west4-a/operations/operation-1629406175532-5c9efb0499490-22bf8217-c53fd451",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vmwareengine.v1.OperationMetadata",
    "createTime": "2021-08-19T20:49:37.261822386Z",
    "endTime": "2021-08-19T22:44:37.529476321Z",
    "target": "projects/example-project/locations/europe-west4-a/privateClouds/example-privatecloud",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.vmwareengine.v1.PrivateCloud",
    "name": "projects/example-project/locations/europe-west4-a/privateClouds/example-privatecloud",
    "createTime": "2021-08-19T20:49:39.230Z",
    "updateTime": "2021-08-19T21:48:26.477Z",
    "state": "ACTIVE",
    "networkConfig": {
      "vmwareEngineNetwork": "projects/example-project/locations/europe-west4/vmwareEngineNetworks/europe-west4-default",
      "managementCidr": "192.168.1.0/24"
    },
    "hcx": {
      "fdqn": "hcx-49305.cdad53b7.europe-west4.gve.goog",
      "internalIp": "192.168.1.13",
      "state": "ACTIVE"
    },
    "nsx": {
      "fdqn": "nsx-49304.cdad53b7.europe-west4.gve.goog",
      "internalIp": "192.168.1.11",
      "state": "ACTIVE"
    },
    "vcenter": {
      "fdqn": "vcsa-49225.cdad53b7.europe-west4.gve.goog",
      "internalIp": "192.168.1.6",
      "version": "7.0.1.17928463",
      "state": "ACTIVE"
    }
  }
}

Poll operations

You can write some code to periodically poll the operation with a get or wait request that returns when the operation is complete.

With a get request, the operation is returned immediately, regardless of the status of the operation. You need to poll the operation regularly to know when the operation is done.

If you make a wait request, the request returns when the operation is complete or if the request approaches the 2 minute deadline. The wait method provides certain benefits over the get method:

• You can set up your clients to poll for the operation status less frequently, reducing your query count to the VMware Engine API.
• The average latency between when the operation is done and when the client is informed that the operation is done is significantly reduced because the server responds as soon as the operation is done.
• The wait method provides bounded waits. The method waits for no more than the default HTTP timeout (2 minutes) and then returns the current state of the operation, which might be complete or in progress.

The wait method is a best-effort API. If the server is overloaded, the request might return before it reaches the default deadline, or after waiting just zero seconds. The method is also not guaranteed to return only when the operation is complete. For example, if the request approaches the 2 minute deadline, the method returns even if the operation is not done. We recommend that you use either the wait or get method with sleep in-between to regularly poll the operation status.

Error messages

When an API response that you receive contains the error field, then the operation encountered an error during processing. Use the error field to differentiate between error types and get more information about what happened.

For example, the following response contains an error message for an operation that attempted to update a private cloud:

{
  "done": true,
  "error": {
    "code": 9,
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.PreconditionFailure",
        "violations": [
          {
            "type": "resource",
            "subject": "projects/1234567891011/locations/asia-northeast1-a/privateClouds/example-privatecloud",
            "description": "`PrivateCloud` resource is already being modified. Wait for all pending operations to complete before making further changes."
          }
        ]
      },
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_IS_BEING_MODIFIED",
        "domain": "vmwareengine.googleapis.com",
        "metadata": {
          "resourceType": "PrivateCloud"
        }
      }
    ],
    "message": "`PrivateCloud` resource is already being modified. Wait for all pending operations to complete before making further changes."
  },
  "name": "projects/example-project/locations/asia-northeast1-a/operations/operation-1653648987302-5dffc2878abff-d667a181-f17c686f",
  "metadata": {
    "createTime": "2022-05-27T10:56:27.671026261Z",
    "endTime": "2022-05-27T10:56:28.038648292Z",
    "target": "projects/example-project/locations/asia-northeast1-a/privateClouds/example-privatecloud",
    "verb": "update",
    "apiVersion": "v1",
    "@type": "type.googleapis.com/google.cloud.vmwareengine.v1.OperationMetadata"
  }
}

Example requests

The following sections contain example curl requests for some common use cases. For details about individual methods and resources, see the REST API reference.

Get a list of locations

To get a list of locations where VMware Engine is supported, use locations.list.

curl -LsX GET "https://vmwareengine.googleapis.com/v1/projects/example-project/locations" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"

Get details of a single node type

To get information about a particular node type, use nodeTypes.get. The following example gets information about the standard-72 node type in the europe-west4-a location:

curl -LsX GET "https://vmwareengine.googleapis.com/v1/projects/example-project/locations/europe-west4-a/nodeTypes/standard-72" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"

Create a private cloud

To request creation of a new private cloud, use privateClouds.create. The following example creates a private cloud using the provided network and management cluster configuration:

curl -X POST "https://vmwareengine.googleapis.com/v1/projects/example-project/locations/europe-west4-a/privateClouds?private_cloud_id=example-privatecloud" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
  "networkConfig":{
    "managementCidr": "192.168.1.0/24"
    "vmwareEngineNetwork": "projects/example-project/locations/europe-west4-a/vmwareEngineNetworks/europe-west4-default",
  },
  "managementCluster":{
    "clusterId": "example-cluster"
    "nodeTypeId": "standard-72",
    "nodeCount": 3,
  },
  "description": "Example description of a private cloud"
}'

Update the number of nodes in a cluster

To change the number of nodes in an existing cluster, use clusters.patch. The following example updates the node count of a cluster using the provided field mask and cluster configuration:

curl -X PATCH "https://vmwareengine.googleapis.com/v1/projects/example-project/locations/europe-west4-a/privateClouds/example-privatecloud/clusters/example-cluster?updateMask=nodeCount" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
  "nodeCount": 5,
}'

Delete a private cloud

To mark a private cloud for deletion, use privateClouds.delete. When a private cloud is marked for deletion, VMware Engine sets an expiration time on the private cloud for when the deletion is final and can no longer be reversed.

The following example marks a private cloud for deletion after 5&hours:

curl -LsX DELETE "https://vmwareengine.googleapis.com/v1/projects/example-project/locations/europe-west4-a/privateClouds/example-private-cloud?delayHours=5" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"

Get details of an operation

To get information about a long-running operation, use operations.get. The following example gets details about an existing operation with the provided operation name:

curl -LsX GET "https://vmwareengine.googleapis.com/v1/projects/example-project/locations/europe-west4-a/operations/operation-1629406175532-5c9efb0499490-22bf8217-c53fd451" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"