This document gives an overview of the Google Cloud Storage XML API and is intended for developers. It assumes that you are familiar with web programming and you are comfortable creating applications that consume web services through HTTP requests.

As an alternative to creating HTTP requests and parsing responses manually using the XML API, you can use the Google APIs client libraries , the gsutil tool, or Google Cloud Storage UI, Google Developers Console .

Contents

• Overview
• Requests
• Responses

Overview

Google Cloud Storage XML API is a RESTful interface that lets you manage Google Cloud Storage data in a programmatic way. As a RESTful API, it relies on method information and scoping information to define the operations to perform:

Method information

You specify the method information with standard HTTP methods, such as DELETE, GET, HEAD, and PUT.

Scoping information

You specify the scoping information with a publicly-accessible endpoint (URI) and various scoping parameters. In this case, the primary scoping parameter is a path to a resource, which consists of an object name (file name) and bucket name (container name). Used together, the object name, bucket name, and public URI create a unique URL to a given resource—a resource on which you can perform operations with HTTP methods. You can further scope your operations by using HTTP headers and query string parameters.

For detailed programming information about the Google Cloud Storage XML API, see the Reference Guide .

We recommend that you use HTTPS when reading or writing data to Google Cloud Storage so that your data is encrypted during transfer. Google Cloud Storage automatically encrypts your data before it is written to disk. For more information, see Server-Side Encryption .

Requests

In practical terms, the Google Cloud Storage XML API provides a web interface for making HTTP requests and handling HTTP responses. Each request implements a standard HTTP method. The Google Cloud Storage XML API supports the following HTTP methods:

• GET Service —lists all of the buckets that you own.
• PUT Bucket —creates a bucket and changes the permissions on a bucket.
• GET Bucket —lists the contents of a bucket or retrieves the ACLs that are applied to a bucket.
• DELETE Bucket —deletes an empty bucket.
• GET Object —downloads an object or retrieves the ACLs that are applied to an object.
• PUT Object —uploads an object or applies new ACLs to an object.
• DELETE Object —deletes an object.
• HEAD Object —lists the metadata for an object.
• POST Object —uploads an object by using HTML forms.

You can use various HTTP request headers with each of these methods. The Google Cloud Storage XML API supports HTTP/1.1 request headers. It also supports several extension (custom) request headers, which have an x-goog- prefix. Request header requirements vary depending on the kind of request you're making, but a few request headers are required for every request. The following table describes some frequently used request headers, including required headers:

The Google Cloud Storage XML API also supports several query string parameters, which you can use to scope your requests. The query string parameters follow the HTTP path portion of the request and must be used in the following standard form:

<path_to_object> /? <parameter> = <value> ? <parameter> = <value> ...

The most frequently-used query string parameters include the following:

• acl —used with PUT and GET requests to change or apply object or bucket permissions.
• delimiter —used with list object requests to limit the scope of the returned list.
• max-keys —used with list object requests to specify the maximum number of objects you want in the returned list.
• marker —used with list object requests to specify which object you want the returned list to begin with.
• prefix —used with list object requests to limit the number of objects that are returned in the list to only those with the given prefix.
• location —used with GET requests to retrieve the geographical location of a bucket.

All requests to Google Cloud Storage must be authenticated, with the exception of requests made to anonymously accessible objects or buckets. For detailed information about how you set the Authorization headers for Google Cloud Storage requests, see Authentication .

Most Google Cloud Storage requests use the following URI for accessing buckets and objects:

storage.googleapis.com

You can scope this further by adding a bucket and object to the URI. The resulting URL can take two forms:

<bucket> .storage.googleapis.com/ <object>

storage.googleapis.com/ <bucket> / <object>

You can use the Google Cloud Storage URI with unsecure requests (HTTP) and secure requests (HTTPS) that use secure sockets layer (SSL) encryption. Google Cloud Storage also provides other request endpoints, which you must use if you are redirecting a request with a CNAME alias or you are providing authenticated browser downloads. For more information, see Request Endpoints later in this document.

A typical authenticated Google Cloud Storage request is shown in the following example. This request retrieves a list of objects that are stored in a bucket named travel-maps. The request limits the list of objects to only those objects that have the prefix /europe/france.

GET /?prefix=/europe/france/ HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Wed, 17 Feb 2010 15:31:56 -0800
Content-Length: 0
x-goog-api-version: 2
Authorization: Bearer 1/zVNpoQNsOSxZKqOZgckhpQ

Back to top

Responses

The Google Cloud Storage XML API returns standard HTTP/1.1 response headers and several extension (custom) response headers. The response headers vary according to the operation you perform. Some frequently-used response headers are listed in the following table:

Responses can also include a status code. Google Cloud Storage uses the standard HTTP/1.1 status codes. Error responses include an XML document in the response body, which contains information about the error conditions.

A typical Google Cloud Storage response is shown in the following example. This example is a response to a list bucket request. The bucket name is travel-maps and the request is scoped so that only objects with the prefix /europe/france/ are returned in the list.

HTTP/1.1 200 OK
Content-Length: 4061
Content-Type: application/xml
Date: Wed, 17 Feb 2010 23:31:57 GMT
Cache-Control: private, max-age=0

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.storage.googleapis.com/2010-03-01'>
  <Name>travel-maps</Name>
  <Prefix>/europe/france/</Prefix>
  <Marker></Marker>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>europe/france/cannes.jpg</Key>
    <LastModified>2010-02-17T22:11:12.487Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>europe/france/paris.jpg</Key>
    <LastModified>2010-02-17T22:09:57.457Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
</ListBucketResult>

Back to top

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .