Google Cloud Platform
Cloud Storage

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.

Contents

  1. HTTP headers and common query string parameters summary
  2. Standard HTTP headers
  3. Extension (custom) HTTP headers
  4. Standard query string parameters

HTTP headers and common query string parameters summary

Standard HTTP Headers

  1. Authorization
  2. Cache-Control
  3. Content-ID
  4. Content-Length
  5. Content-Range
  6. Content-Type
  7. Content-Transfer-Encoding
  8. Date
  9. ETag
  10. Expires
  11. Host
  12. If-Match
  13. If-None-Match
  14. Location
  15. Range

Extension (Custom) HTTP Headers

  1. X-HTTP-Method-Override
  2. X-Upload-Content-Length
  3. X-Upload-Content-Type

Query String Parameters

  1. access_token
  2. callback
  3. fields
  4. key
  5. prettyPrint
  6. quotaUser
  7. userIp

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 will receive a MissingSecurityHeader error and your request will be rejected. For more information about accessing Google Cloud Storage through a proxy server, see the FAQ.

For additional details, see the specification.

Back to top


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.

Back to top


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.

Back to top


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.

Back to top


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 (first 2000 bytes)

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 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.

Back to top


Content-Transfer-Encoding

An optional request and response header that indicates the type of encoding that has been applied to the message body.

Valid Values

The type of encoding the body is in.

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.

Back to top

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.

Back to top


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.

Back to top


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.

Examples

ETag: "39a59594290b0f9a30662a56d695b71d"

ETag: "-CKicn4fknbUCEAE="

Implementation Details

See the specification.

Back to top


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.

Back to top


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.

Back to top


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.

Back to top


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.

Back to top


Range

A header used in some upload responses and download requests.

Valid Values

Any valid byte range.

Example

Range: bytes=0-1999

Implementation Details

In the Google 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 file uploads.

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

Back to top


Extension (custom) HTTP headers

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.

Back to top


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.

Back to top


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.

Back to top


Standard Query Parameters

Query parameters that apply to all Google Cloud Storage JSON API operations are shown in the table below.

Notes (on API keys and auth tokens):

  1. 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.
  2. You must send an authorization token with every request that is marked (AUTHENTICATED). OAuth 2.0 is the preferred authorization protocol.
  3. 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.
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 Platform 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 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 usage.