This document describes how to construct API requests and handle API responses from the Compute Engine API. It covers how to:
- 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 authorize to the API. To learn how to authorize to the API, read Authorizing requests.
Before you begin
- Familiar with REST APIs.
- Know how to authorize requests to the Compute Engine API.
Constructing an API request
The Compute Engine API expects API requests to be in JSON
format. To make an API request, you can either make a direct HTTP request, using
tools like curl
or httplib2
, or you can use one of the
available client libraries.
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 want to set in this request. For example, the following curl
command
makes a POST
request to the Instances resource URI. The request creates an
instance with the properties defined in the request body:
curl -X POST -H "Authorization: Bearer [OAUTH_TOKEN]" -H "Content-Type: application/json" https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances -d '{ "disks":[ { "boot":"true", "initializeParams":{ "sourceImage":"https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-8-jessie-v20160301" } } ], "machineType":"https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/machineTypes/e2-standard-2", "name":"[INSTANCE_NAME]", "networkInterfaces":[ { "accessConfigs":[ { "name":"external-nat", "type":"ONE_TO_ONE_NAT" } ], "network":"https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/networks/default" } ] }'
In this case, the request body is indicated by the -d
flag, and looks like
this (formatted for easier viewing):
{ "disks":[ { "boot":"true", "initializeParams":{ "sourceImage":"https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-8-jessie-v20160301" } } ], "machineType":"https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/machineTypes/e2-standard-2", "name":"[EXAMPLE_INSTANCE]", "networkInterfaces":[ { "accessConfigs":[ { "name":"external-nat", "type":"ONE_TO_ONE_NAT" } ], "network":"https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/networks/default" } ] }
Notice that:
When referencing another resource, use the fully qualified resource URI. For example, the
network
property uses a fully-qualified URI to thedefault
network.The image URI has a different project ID (
debian-cloud
) from your project ID. This is because images belong to different projects, depending on the type of image. For example, all publicly available Debian images offered by Compute Engine are hosted on thedebian-cloud
project.
Here are other examples of API requests using the Python and Java client libraries.
Python
Java
Creating resource URIs
In the earlier examples, a reference to another Google Cloud resource is given as a fully qualified URI that looks like this:
https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/[RESOURCE_TYPE]/[SPECIFIC_RESOURCE]
Whenever you specify an image, a machine type, a network, or any other resource,
you must provide the URI to the resource when using the API. Client tools like
the gcloud
command-line tool and the Google Cloud Console hide this complexity and handle
creating these resource URIs for you, but when interacting with the API
directly, you must create these resource URIs yourself.
There are slightly different resource URIs for different types of resources. For
example, a zonal resource has the zone
specification in the URI, like so:
https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/machineTypes/e2-standard-2
Regional resources replace the zone
specification with a region
specification:
https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/regions/[REGION]/addresses/[ADDRESS_NAME]
Similarly, global resources have the global
specification:
https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/images/[IMAGE_NAME]
The Compute Engine API also accepts partial URIs because the service can infer information like the project ID. So, the following partial versions of the earlier URIs are also acceptable:
zones/[ZONE]/machineTypes/e2-standard-2
regions/[REGION]/addresses/[ADDRESS_NAME]
project/[PROJECT_ID]/global/images/[IMAGE_NAME]
In the partial URIs, both the zonal and regional URIs omitted the project
ID but the image URI did not. This is because publicly available images offered
by Compute Engine are hosted in other projects, like debian-cloud
for
all Debian images and ubuntu-os-cloud
for all Ubuntu images. Before you can
use these images, you need to provide the appropriate project ID. If you omitted
the project ID for images, Compute Engine attempts to find the image in
your project and the request fails because the image does not exist.
However, if you use a custom image that belongs to your project (the same project you are creating this resource in), you can omit the project specification when providing an image URI.
Determining required properties
The Compute Engine API reference documentation, available for both
v1
and
beta APIs, describe 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 an [Output Only]
in the property description), but to determine
required properties for a resource, you need to review the documentation
specific to that task.
For example, if you are creating an instance, read the Creating an instance from an image documentation to see the API properties required for the request. If you want to create a static external IP address in the API, read the Static external IP addresses documentation.
Alternatively, you can validate your API requests in the API explorer, as a quick and easy way to check your code.
Validating API requests
To validate your API requests:
- In the Compute Engine API reference,
find the method your code is calling. For example,
v1/compute.instances.insert
. From the contents menu, click Try it! This opens the Try this API window.
In the Try this API window, paste your request into the Request body text area. You do not need to provide a project or zone since validation doesn't require submitting the request.
Malformed elements of the request are underlined in blue. Click each underlined section for an explanation of the issue to be addressed.
Handling API responses
If you make a request that mutates data, Compute Engine returns an Operations object that you can then poll to get the status of your request. The Operation resource looks like this:
{ "kind": "compute#operation", "id": "7127550864823803662", "name": "operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b", "zone": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]", "operationType": "insert", "targetLink": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[EXAMPLE_INSTANCE]", "targetId": "4132355614508179214", "status": "PENDING", "user": "user@example.com", "progress": 0, "insertTime": "2016-03-24T14:53:37.788-07:00", "selfLink": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/operations/operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b" }
If the original request was to mutate a zonal resource, like an instance
or a disk, Compute Engine returns a
zoneOperations
object. Similarly, regional and global resources return a
regionOperations
and globalOperations
object, respectively. You can get the status of an operation by performing a
GET
or WAIT
request to the specific Operation resource, providing the name
of
the operation.
Your request is not complete until the Operation resource's status returns as
DONE
. This can take some time depending on the nature of your request. Then,
after the operation's status returns as DONE
, you can check to see if
the operation succeeded and whether there were any errors.
For example, the following response indicates that the same operation that
appears above is now complete, specified by the DONE
status:
endTime: '2016-03-24T14:54:07.119-07:00' id: '7127550864823803662' insertTime: '2016-03-24T14:53:37.788-07:00' kind: compute#operation name: operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b operationType: insert progress: 100 selfLink: https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/operations/operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b startTime: '2016-03-24T14:53:38.397-07:00' status: DONE targetId: '4132355614508179214' targetLink: https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[EXAMPLE_INSTANCE] user: user@example.com zone: https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]
To confirm, make a GET
request to the resource to check that
it exists and is running. For example:
GET /compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[EXAMPLE_INSTANCE] { "cpuPlatform": "Intel Haswell", "creationTimestamp": "2016-03-24T14:53:37.170-07:00", "disks": [ ..[snip].. "selfLink": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[EXAMPLE_INSTANCE]", "status": "RUNNING", "tags": { "fingerprint": "42WmSpB8rSM=" }, "zone": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]" }
Polling operations
You can write some code to periodically poll the operation with a GET
or WAIT
request that returns when the operation status is DONE
. With a GET
request,
the operation is returned immediately, regardless of the status of the operation.
You will then 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
DONE
or if the request is approaching the 2 minute deadline. You can choose to
use WAIT
or GET
to poll your operations, but 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 QPS usage of the Compute 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. With the
GET
request, it is up to the client to check whether the operation is done. - The 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
DONE
or still in progress.
The WAIT
method is intended to be 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 DONE
. For example, if the request approaches the 2 minute
deadline, the method returns even if the operation is not done. We still
recommend that you regularly poll the operation status with the WAIT
or GET
methods with sleep in-between, to check on your operations.
Here are some examples of polling in Python and Java using the GET
method.
You can also replace the GET
method with the WAIT
method: