HTTP headers and common query string parameters for JSON

The Cloud Storage API uses several standard HTTP headers as well as several extension (custom) HTTP headers. Numerous query string parameters are also supported; those parameters that apply to all Google Cloud Storage JSON API operations are shown below. See specific methods for a complete list of query string parameters that each method supports.

HTTP headers and common query string parameters summary

The JSON API uses the following standard HTTP headers:

Authorization
Cache-Control
Content-ID
Content-Length
Content-Range
Content-Type
Content-Transfer-Encoding
Date
ETag
Expires
Host
If-Match
If-None-Match
Location
Range

The JSON API uses the following extension (custom) HTTP headers:

X-Goog-Content-Length-Range
X-Goog-Encryption-Algorithm
X-Goog-Encryption-Key
X-Goog-Encryption-Key-Sha256
X-Goog-Copy-Source-Encryption-Algorithm
X-Goog-Copy-Source-Encryption-Key
X-Goog-Copy-Source-Encryption-Key-Sha256
X-Goog-User-Project
X-HTTP-Method-Override
X-Upload-Content-Length
X-Upload-Content-Type

The JSON API uses the following query string parameters:

access_token
alt
callback
fields
key
prettyPrint
quotaUser
userIp userProject

Standard HTTP headers

Authorization

A request header that contains a string used to authenticate requests.

Valid Values An authentication identifier ( Bearer | GOOG1 | AWS ) followed by one of the following:
  • A valid OAuth 2.0 token
  • An access key
  • A signature
Example Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s- ...
Implementation Details For more information about how to use this header, see Authentication.

Note: If your requests are being routed through a proxy, you may need to check with your network administrator to ensure that the Authorization header containing your credentials is not stripped out by the proxy. Without the Authorization header, you receive a MissingSecurityHeader error and your request is rejected. For more information about accessing Cloud Storage through a proxy server, see the Troubleshooting topic.

For additional details, see the specification.

Cache-Control

A request and response header that specifies the cache-control setting.

Valid Values Any valid cache-control value (see the specification).
Example Cache-Control: public, max-age=6000
Implementation Details You can specify cache-control in a request only for objects that are accessible to all anonymous users. To be anonymously accessible, an object's ACL must grant READ or FULL_CONTROL permission to AllUsers. If an object is accessible to all anonymous users and you do not specify a cache-control setting, Cloud Storage applies a cache-control setting of 3600 seconds. When serving via JSON, Cloud Storage sets the cache-control of the response to no-cache for any object that is not anonymously accessible, regardless of the metadata settings for the object. For additional details, see the specification.

Content-ID

An optional identifier in the part-header of a multipart request.

Valid Values An identifier that is unique within the parts of the request.
Example Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+1>
Implementation Details Content-ID is only used in the body of multipart (batch) requests and only as an identifier of requests within the body. If included, any response will have a matching Content-ID header in the corresponding part whose value will be response- followed by the originally supplied ID. For additional details, see the specification.

Content-Length

The length (in bytes) of the request or response body.

Valid Values Any value of zero or greater.
Example Content-Length: 1234
Implementation Details This is required for most POST and PUT commands used in uploading objects, except if you are using chunked transfer encoding. When making the initial request of a resumable upload, this header should be set to the number of bytes provided in that specific request. For more information, see the upload How-To for JSON. For additional details, see the specification.

Content-Range

A header used in some upload requests and download responses.

Valid Values Any contiguous range of bytes.
Example Content-Range: bytes 456-987/1234
Implementation Details

The content-range header is used as a response header indicating the range of bytes being returned following a request with a Range header. Additionally, it is used as a request header when resuming an interrupted upload, either as a request to find the current position of the upload prior to interruption or as an indicator of the starting point of the remaining chunk to be uploaded. In a similar manner, the header is used in chunked resumable uploads.

Byte ranges are inclusive; that is, bytes=0-999 represent the first 1000 bytes in a file or object.

For additional details, particularly regarding download responses, see the specification.

Content-Transfer-Encoding

A header used in some upload requests and download responses.

Valid Values An optional request and response header that indicates the type of encoding that has been applied to the message body.
Example Content-Transfer-Encoding: binary
Implementation Details

This header specifies the encoding of a message body in a request.

For additional details, see the specification.

Content-Type

The MIME type of the request or response.

Valid Values Any valid MIME type.
Example Content-Type: text/html
Implementation Details

This is required for POST and PUT commands associated with uploading objects and granting permissions; however, this command can alternatively be included in the body of the request instead of as a header (for more information, see the upload How-To for JSON). When making the initial request of a resumable upload that also includes metadata, use the Content-Type header to specify the metadata's data type.

For additional details, see the specification.

Date

The date and time of the request or response.

Valid Values A date and time represented in conventional HTTP format (see the specification).
Example Date: Wed, 16 Jun 2010 11:11:11 GMT
Implementation Details For information about HTTP date formats, see the specification.

ETag

A response header that contains the entity tag of the object being accessed.

Valid Values A string of characters enclosed by quotes. For more information, see Hashes and ETags: Best Practices.
Example

ETag: "39a59594290b0f9a30662a56d695b71d"

ETag: "-CKicn4fknbUCEAE="

Implementation Details See the specification.

Expires

A response header indicating the time after which the response is considered stale.

Valid Values A date and time represented in conventional HTTP format (see the specification).
Example Expires: Tue, 22 Jan 2013 18:56:00 GMT
Implementation Details See the specification.

If-Match

A request header that specifies an entity tag (ETag).

Valid Values A valid entity tag.
Example If-Match: "881f7881ac1bc144a2672e45babb8839"
Implementation Details

Only a single entity tag (not a comma-separated list of entity tags) can be specified. This header is supported for all resources, including buckets, objects and ACLs. If the ETag you specify with this header is the same as the ETag for the object, then the metadata or the object is returned. For an object that uses Etags, patch requests on that object must include an if-match header along with the object's ETag. If the ETag you specify with this header is different from the ETag for the object, then the metadata or the object is not returned (nor are patch requests executed) and Cloud Storage returns a 412 Precondition Failed error code.

For additional details, see the specification.

If-None-Match

A request header that specifies an entity tag (ETag).

Valid Values A valid entity tag.
Example If-None-Match: "881f7881ac1bc144a2672e45babb8839"
Implementation Details

This header is supported for all resources, including buckets, objects and ACLs. If the ETag you specify with this header is different from the ETag for the object, then the metadata or the object is returned. If the ETag you specify with this header is the same as the ETag of the object, then the metadata or the object is not returned and Cloud Storage returns a 304 Not Modified status code.

For additional details, see the specification.

Location

A response header providing a URI.

Valid Values Any valid URI.
Example Location: https://example.storage.googleapis.com/?upload_id=tvA0...rot
Implementation Details

The location header is used for several purposes:

  • In response to initiating a resumable upload it provides you with a session URI for a resumable upload operation.
  • In response to a Cookie-based authentication request it provides you with a unique web origin response URL for the request. See Cookie-based authentication for more details.
  • In response to a JSON API download request made at a URL other than www.googleapis.com/download it provides a redirect to the JSON API URL where the download can be made.

For additional details, see the specification.

Range

A header used in some upload responses and download requests.

Valid Values Any valid byte range.
Example Range: bytes=0-1999 (first 2000 bytes)
Implementation Details

In the Cloud Storage JSON API, the range header is used to determine the number of bytes currently uploaded after an interruption in a resumable upload. It also appears in the response header of chunked resumable uploads.

For additional information, particularly regarding download requests, see the specification.

Extension (custom) HTTP headers

X-Goog-Content-Length-Range

A PUT request header. When used, Cloud Storage only accepts the request if the size of the request's content is within the header's specified range.

Valid Values A [MIN],[MAX] pair
Example X-Goog-Content-Length-Range: 0,256
Implementation Details The values for content size are inclusive and given in bytes. If the size of the request's content is in the specified range, it is delivered as requested. If the size of the request's content is outside the specified range, the request fails and a 400 Bad Request code is returned in the response. If the X-Goog-Content-Length-Range is used in a request other than PUT, the header is silently ignored.

X-Goog-Encryption-Algorithm

A request and response header that specifies the encryption algorithm to use.

Valid Values AES256
Example X-Goog-Encryption-Algorithm: AES256
Implementation Details This request and response header is used when you provide customer-supplied encryption keys. When used specifically in a rewrite operation, this header applies to the destination object.

X-Goog-Encryption-Key

A request header that specifies an encryption key.

Valid Values An RFC 4648 Base64-encoded string of a valid AES-256 encryption key
Example X-Goog-Encryption-Key: NwbyGGmcKAX4FxGpOERG2Ap33m5NVOgmXznSGTEvG0I=
Implementation Details This request header is used when you provide customer-supplied encryption keys. When used specifically in a rewrite operation, this header applies to the destination object.

X-Goog-Encryption-Key-Sha256

A request and response header that specifies the SHA256 hash of the encryption key.

Valid Values An RFC 4648 Base64-encoded string of a valid SHA256 hash for an encryption key
Example X-Goog-Encryption-Key-Sha256: +eBzkZBt1Mj2CZx69L3c8yXoZB6DtRLlSvXMJB9JGIQ=
Implementation Details This request header is used when you provide customer-supplied encryption keys. When used specifically in a rewrite operation, this header applies to the destination object.

X-Goog-Copy-Source-Encryption-Algorithm

A request and response header that specifies the encryption algorithm to use on the source object when performing a rewrite.

Valid Values AES256
Example X-Goog-Copy-Source-Encryption-Algorithm: AES256
Implementation Details This request and response header is used in rewrite operations when you provide customer-supplied encryption keys. This header applies to the source object used in the rewrite.

X-Goog-Copy-Source-Encryption-Key

A request header that specifies an encryption key to use to decrypt the source object when performing a rewrite.

Valid Values An RFC 4648 Base64-encoded string of a valid AES-256 encryption key
Example X-Goog-Copy-Source-Encryption-Key: NwbyGGmcKAX4FxGpOERG2Ap33m5NVOgmXznSGTEvG0I=
Implementation Details This request header is used in rewrite operations when you provide customer-supplied encryption keys. This header applies to the source object in the rewrite.

X-Goog-Copy-Source-Encryption-Key-Sha256

A request and response header that specifies the SHA256 hash of the encryption key that is used to decrypt the source object when performing a rewrite.

Valid Values An RFC 4648 Base64-encoded string of a valid SHA256 hash for an encryption key
Example X-Goog-Copy-Source-Encryption-Key-Sha256: +eBzkZBt1Mj2CZx69L3c8yXoZB6DtRLlSvXMJB9JGIQ=
Implementation Details This request header is in rewrite operations when you provide customer-supplied encryption keys. This header applies to the source object in the rewrite.

X-Goog-User-Project

A request header that specifies a user project to bill for access charges associated with the request.

Valid Values The Project ID for an existing Google Cloud project
Example X-Goog-User-Project: my-project
Implementation Details

The project specified in the header is billed for charges associated with the request. This header is used, for example, when making requests to buckets that have Requester Pays enabled.

Generally, JSON requests that require a project ID should supply one in the request URL with the userProject parameter instead of with the X-Goog-User-Project header.

X-HTTP-Method-Override

An alternative notation for sending PATCH commands.

Valid Values PATCH
Example X-HTTP-Method-Override: PATCH
Implementation Details The X-HTTP-Method-Override header can be sent with a POST command in order to make the command behave as a PATCH command. This is useful when your firewall does not allow explicit PATCH commands to be sent.

X-Upload-Content-Length

A request header used in resumable uploads.

Valid Values Any value of 0 or greater.
Example X-Upload-Content-Length: 2000000
Implementation Details The X-Upload-Content-Length header is used in the initial request of a resumable upload. It specifies the number of bytes of upload data that will be transferred in subsequent requests. If the length is unknown at the time of this request, the header can be omitted.

X-Upload-Content-Type

A request header used in resumable uploads.

Valid Values Any valid MIME type (see the specification).
Example X-Upload-Content-Type: image/jpeg
Implementation Details The X-Upload-Content-Type header is used in the initial request of a resumable upload. It specifies the MIME media type of the data that will be transferred in the resumable upload.

Standard Query Parameters

Query parameters can be used in any JSON API request are shown in the table below. Note that not all parameters apply to all requests. For example, use of the fields parameter has no effect on Delete requests, since the response body is empty.

Notes (on API keys and auth tokens):

  • For authenticated requests, the key parameter is required, unless you provide an OAuth 2.0 token with the request. For anonymous requests, such as requests for publicly shared resources, the key is not required.
  • You must send an authorization token with every request that requires an OAuth scope. OAuth 2.0 is the only supported authorization protocol.
  • You can provide an OAuth 2.0 token with any request in one of two ways:
    • Using the access_token query parameter like this: ?access_token=oauth2-token
    • Using the HTTP Authorization header like this: Authorization: Bearer oauth2-token

All parameters are optional except where noted.

Parameter Meaning Notes
access_token OAuth 2.0 token for the current user.
alt

Data format for the response.

  • Valid values: json, media
  • Default value: json
callback Callback function.
  • Name of the JavaScript callback function that handles the response.
  • Used in JavaScript JSON-P requests.
fields Selector specifying a subset of fields to include in the response.
  • For more information, see the partial response documentation.
  • Use for better performance.
key API key. (REQUIRED*)
  • *Required for authenticated requests unless you provide an OAuth 2.0 token. For anonymous requests, the key is not required.
  • Your API key identifies your project and provides you with API access, quota, and reports.
  • Obtain your project's API key from the Google Cloud Console.
prettyPrint

Returns response with indentations and line breaks.

  • Returns the response in a human-readable format if true.
  • Default value: true.
  • When this is false, it can reduce the response payload size, which might lead to better performance in some environments.
quotaUser Alternative to userIp.
  • Lets you enforce per-user quotas from a server-side application even in cases when the user's IP address is unknown. This can occur, for example, with applications that run cron jobs on App Engine on a user's behalf.
  • You can choose any arbitrary string that uniquely identifies a user, but it is limited to 40 characters.
  • Overrides userIp if both are provided.
  • Learn more about Capping API usage.
userIp IP address of the end user for whom the API call is being made.
  • Lets you enforce per-user quotas when calling the API from a server-side application.
  • Learn more about Capping API usage.
userProject The project to be billed for the request.