XML API overview
This document gives an overview of the Cloud Storage XML API and is intended forsoftware developers. It assumes that you are familiar with RESTful services andweb programming and that you are comfortable creating applications that operatethrough HTTP requests. If this does not describe you, consider one of thefollowing alternatives:
If you are just starting out with Cloud Storage, you should first tryeither theGoogle Cloud console Quickstart or theGoogle Cloud CLI Quickstart. These tutorials demonstrate the basics ofusing Cloud Storage without the need to use the API directly.
If you work in certain programming languages, you can usetheCloud Storage Client Libraries.
If you are a mobile or web app developer, you can use theFirebase SDKsfor Cloud Storage.
If you are not a software developer and want to store your personal data inthe cloud and share it with others, you can useGoogle Drive.
Overview
The Cloud Storage XML API is a RESTful interface that lets you manageCloud Storage data in a programmatic way. As a RESTful API, it relies onmethod information andscoping information to define the operations toperform:
Method information
You specify the method information with standard HTTP methods, such as
DELETE,GET,HEAD, andPUT.Scoping information
You specify the scoping information with apublicly-accessible endpoint(URI) and various scoping parameters. For the XML API, the primary scopingparameters are the bucket and object names. You can further scopeyour operations by usingHTTP headers and query string parameters.
You use HTTP methods to perform operations on the resource you specify in thescope. For a list of operations available in the XML API, seeXML API Request Methods.
Access to Cloud Storage through the XML API is useful when you are usingtools and libraries that must work across different storage providers, orwhen you are migrating from another storage provider to Cloud Storage. In thelatter case, you only need to make a few simple changes to your existing toolsand libraries to begin sending requests to Cloud Storage. For moreinformation about migrating to Cloud Storage, seeSimple migration from Amazon S3 to Cloud Storage.
Requests
Note: We recommend that you use HTTPS when reading or writing data toCloud Storage so that your data is encrypted during transfer.Cloud Storage automatically encrypts your data before it is written todisk. For more information, seeEncryption.The Cloud Storage XML API provides a web interface for making HTTPrequests 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.
Authentication
All requests to Cloud Storage must be authenticated, with the exceptionof requests made to anonymously accessible objects or buckets. Requests aretypically authenticated using theAuthorization header.
Endpoints
Important: If you intend to serve content through a browser, note that the XMLAPI serves content from the same origin as the request endpoint. If you need toserve content from a unique origin, consider using the JSON API orAuthenticated browser downloads.Most Cloud Storage XML API requests use the following URI for accessingbuckets and objects:
storage.googleapis.com
You can scope this further by adding a bucket and object to the URI. Theresulting URL can take two forms:
BUCKET_NAME.storage.googleapis.com/OBJECT_NAMEstorage.googleapis.com/BUCKET_NAME/OBJECT_NAME
You can use the Cloud Storage URI with unsecured requests (HTTP) and securedrequests (HTTPS) that use secure sockets layer (SSL) encryption.
For additional endpoints, such as dedicated upload and download endpointsfor the XML API, seeRequest Endpoints.
Headers and query string parameters
The Cloud Storage XML API supports HTTP request headers. It alsosupports several extension (custom) request headers, which have anx-goog-prefix. Request header requirements vary depending on the kind of request you'remaking. Some frequently used request headers include:
| Request Header | Description | Usage |
|---|---|---|
Authorization | The authentication string for requests. | Required for all authenticated requests. |
Content-Length | The size of the request body (excluding headers) in bytes. | Required for all PUT and POST requests, except chunked transfers. |
Content-Type | The MIME type of the request body, such asapplication/xml ortext/html. | Recommended for requests that contain an entity body. |
Date | The date and time of the request. | Required for all requests, except forsigned URLs, which can usex-goog-date instead. |
Host | The URI for the request. | Required for all requests. |
x-goog-project-id | 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, seeSimple 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 theHTTP path portion of the request with the following syntax:
PATH_TO_OBJECT/?PARAMETER=VALUE&PARAMETER=VALUE...
For a complete list of XML API headers and query string parameters, seeHTTP headers and query string parameters.
Example request
A typical authenticated Cloud Storage request is shown in the followingexample. This requestretrieves a list of objects that are stored in abucket namedtravel-maps. The request limits the list of objects to only thoseobjects that have the prefix/europe/france.
GET /?list-type=2&prefix=/europe/france/ HTTP/1.1Host: travel-maps.storage.googleapis.comDate: Wed, 17 Feb 2010 15:31:56 -0800Content-Length: 0Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Responses
The Cloud Storage XML API returns standard HTTP response headers andseveral extension (custom) response headers. The response headers vary accordingto the operation you perform. Some frequently used response headers include:
| Response Header | Description |
|---|---|
Cache-Control | The cache control setting for the response. |
Content-Length | The size of the response body (excluding headers) in bytes. |
Content-Type | The MIME type of the response body, such asapplication/xml ortext/html. |
Date | The date and time of the response. |
ETag | AnHTTP 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 standardHTTP status codes. An error response includes an XML document in theresponse body, which contains information about the error conditions. For alist of status codes used by the XML API, seeHTTP Status and Error Codes.
A typical Cloud Storage response is shown in the following example. Thisexample is a response to a request forlisting a bucket's contents. Thebucket name istravel-maps and the request is scoped so that only objectswith the prefix/europe/france/ are returned in the list.
HTTP/1.1 200 OKContent-Length: 4061Content-Type: application/xmlDate: Wed, 17 Feb 2010 23:31:57 GMTCache-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>
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-10-24 UTC.