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://compute.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-8-jessie-v20160301" } } ], "machineType":"https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/machineTypes/n1-standard-1", "name":"[INSTANCE_NAME]", "networkInterfaces":[ { "accessConfigs":[ { "name":"external-nat", "type":"ONE_TO_ONE_NAT" } ], "network":"https://compute.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://compute.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-8-jessie-v20160301" } } ], "machineType":"https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/machineTypes/n1-standard-1", "name":"[EXAMPLE_INSTANCE]", "networkInterfaces":[ { "accessConfigs":[ { "name":"external-nat", "type":"ONE_TO_ONE_NAT" } ], "network":"https://compute.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 sightly 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/n1-standard-1
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/n1-standard-1
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.
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://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]", "operationType": "insert", "targetLink": "https://compute.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://compute.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
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://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[EXAMPLE_INSTANCE]", "status": "RUNNING", "tags": { "fingerprint": "42WmSpB8rSM=" }, "zone": "https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]" }
Polling operations
You can write some code to periodically poll the operation and return when the
operation status is DONE
. Here are some examples of
polling in Python and Java.