This document gives an overview of the Cloud Storage XML API and is intended for software developers. It assumes that you are familiar with RESTful services and web programming and that you are comfortable creating applications that operate through HTTP requests. If this does not describe you, consider one of the following alternatives:
If you are just starting out with Cloud Storage, you should first try either the console Quickstart or the gsutil Quickstart. These tutorials demonstrate the basics of using Cloud Storage without the need to use the API directly.
If you work in certain programming languages, you can use the Cloud Storage Client Libraries.
If you are a mobile or web app developer, you can use the Firebase SDKs for Cloud Storage.
If you are not a software developer and want to store your personal data in the cloud and share it with others, you can use Google Drive.
The Cloud Storage XML API is a RESTful interface that lets you manage 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:
You specify the method information with standard HTTP methods, such as
You specify the scoping information with a publicly-accessible endpoint (URI) and various scoping parameters. For the XML API, the primary scoping parameters are the bucket and object names. You can further scope your operations by using HTTP headers and query string parameters.
You use HTTP methods to perform operations on the resource you specify in the scope. For a list of operations available in the XML API, see XML API Request Methods.
Access to Cloud Storage through the XML API is useful when you are using tools and libraries that must work across different storage providers, or when you are migrating from another storage provider to Cloud Storage. In the latter case, you only need to make a few simple changes to your existing tools and libraries to begin sending requests to Cloud Storage. For more information about migrating to Cloud Storage, see Simple migration from Amazon S3 to Cloud Storage.
The Cloud Storage XML API provides a web interface for making HTTP requests and handling HTTP responses. The API is compatible with HTTP/1.1, HTTP/2, and HTTP/3 protocols. Each request implements a standard HTTP method. Along with these methods, you can use various HTTP request headers.
All requests to 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 Cloud Storage requests, see Authentication.
Most Cloud Storage XML API requests use the following URI for accessing buckets and objects:
You can scope this further by adding a bucket and object to the URI. The resulting URL can take two forms:
You can use the Cloud Storage URI with unsecured requests (HTTP) and secured requests (HTTPS) that use secure sockets layer (SSL) encryption.
For additional endpoints, such as dedicated upload and download endpoints for the XML API, see Request Endpoints.
Headers and query string parameters
The Cloud Storage XML API supports HTTP request headers. It also
supports several extension (custom) request headers, which have an
prefix. Request header requirements vary depending on the kind of request you're
making. Some frequently used request headers include:
||The authentication string for requests.||Required for all authenticated requests.|
||The size of the request body (excluding headers) in bytes.||Required for all PUT and POST requests, except chunked transfers.|
||The MIME type of the request body, such as
||Recommended for requests that contain an entity body.|
||The date and time of the request.||Required for all requests.|
||The URI for the request.||Required for all requests.|
||The ID of the project you want to use.||Required for creating buckets or listing buckets except when you are using the XML API for interoperability, such as for compatibility with Amazon S3. For more information, see Simple migration from Amazon S3 to Cloud Storage.|
The Cloud Storage XML API also supports a variety of query string parameters, which you can use to scope your requests. Append query string parameters to the HTTP path portion of the request with the following syntax:
For a complete list of XML API headers and query string parameters, see HTTP headers and query string parameters.
A typical authenticated Cloud Storage request is shown in the following
example. This request retrieves a list of objects that are stored in a
travel-maps. The request limits the list of objects to only those
objects that have the prefix
GET /?list-type=2&prefix=/europe/france/ HTTP/1.1 Host: travel-maps.storage.googleapis.com Date: Wed, 17 Feb 2010 15:31:56 -0800 Content-Length: 0 Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
The Cloud Storage XML API returns standard HTTP response headers and several extension (custom) response headers. The response headers vary according to the operation you perform. Some frequently used response headers include:
||The cache control setting for the response.|
||The size of the response body (excluding headers) in bytes.|
||The MIME type of the response body, such as
||The date and time of the response.|
||An HTTP 1.1 entity tag, which you can use to determine whether an object has changed.|
Responses can also include a status code. Cloud Storage uses standard HTTP status codes. An error response includes an XML document in the response body, which contains information about the error conditions. For a list of status codes used by the XML API, see HTTP Status and Error Codes.
A typical Cloud Storage response is shown in the following example. This
example is a response to a request for listing a bucket's contents. 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> <StartAfter></StartAfter> <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> </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> </Contents> </ListBucketResult>