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:

alt
callback
fields
key
prettyPrint
quotaUser
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- ...
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
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>
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
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 Objects:insert. 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
Details

When appearing in a response, the Content-Range header indicates the range of bytes being returned as a result of a request that included a Range header.

When included as part of a resumable upload request, Content-Range is used to query for the current position of the upload or as an indicator of the starting point of the block of data being uploaded in the current request.

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
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
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 Objects: insert). 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
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="

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
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"
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"
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
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 request header indicating the range of bytes that you want returned, and a response header indicating the range of bytes that have been uploaded to the Cloud Storage system.

Valid Values Any valid byte range.
Examples Range: bytes=0-1999 (first 2000 bytes)
Range: bytes=-2000 (last 2000 bytes)
Range: bytes=2000- (from byte 2000 to end of file)
Details

When included as a header in a request for object data, only the specified range of bytes for the object gets returned, which is useful when resuming interrupted uploads. Be aware that in certain circumstances the range request header is ignored.

When returned as part of a response associated with a resumable upload, Range indicates the number of bytes currently uploaded. You can subsequently use this information to continue the upload.

Byte ranges are inclusive. For example, bytes=0-999 represent the first 1000 bytes in a file or object. For more information about this header, 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
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
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=
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=
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
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=
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=
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
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
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
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
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. If a MIME type is not specified in metadata or through this header, the object is served as application/octet-stream.

Standard Query Parameters

Query string parameters that 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. See specific methods for additional query string parameters.

In the examples of query parameters described in this section, the URIs are not shown but are assumed to be relative to https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE, with the exception of object uploads and batched requests. For more information about the URIs you should use when making requests to the JSON API, see Request endpoints.

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 OAuth access token with every request that requires an OAuth scope. OAuth 2.0 is the only supported authorization protocol.
    • You can send an OAuth 2.0 access token with any request by using the the Authorization header like this: Authorization: Bearer oauth2-token

All parameters are optional except where noted.

Parameter Meaning Notes
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 IP address of the end user for whom the API call is being made.
  • 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.
  • Learn more about Capping API usage.
userProject The project to be billed for the request.

What's next