Cloud Storage JSON API overview

The Cloud Storage JSON API is a simple, JSON-backed interface for accessing and manipulating Cloud Storage projects in a programmatic way. It is fully compatible with the Cloud Storage Client Libraries.

The JSON API is intended for software developers. To use it you should be familiar with web programming and be comfortable creating applications that consume web services 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 Google Cloud console Quickstart or the Google Cloud CLI Quickstart. These tutorials demonstrate the basics of using Cloud Storage without the need to use the API directly.
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 current release of the JSON API is v1.

Partial response

By default, when Cloud Storage sends a resource in a response, it sends the full representation of the resource. For better performance, you can ask Cloud Storage to send only the fields you specify. This is called a partial response.

To request a partial response, use the fields request parameter to specify the fields you want returned. You can use this parameter with any request that returns response data. The fields parameter only affects the response data; it does not affect the data that you need to send, if any. To reduce the amount of data you send when modifying resources, use a PATCH request.

Syntax summary

The format of the fields request parameter value is loosely based on XPath syntax. When using the fields parameter, follow these guidelines:

Use a comma-separated list to return multiple fields.

For example, fields=name,generation,size.
Use a/b to return a field b that is nested within field a; use a/b/c to return a field c nested within b.

For example, fields=metadata/key1.
By default, if your request specifies particular fields, the server returns the objects or array elements in their entirety.Use a sub-selector to request a set of specific sub-fields of arrays or objects by placing expressions in parentheses.

For example: fields=items(id,metadata/key1) returns only the item ID and the key1 custom metadata for each element in the items array. You can also specify a single sub-field, where fields=items(id) is equivalent to fields=items/id.
Each field specified in fields is relative to the root of the response. So if you are performing an operation to list objects, the response is a collection that includes as part of it an array of objects. If you are performing an operation that returns a single object or bucket, fields are specified relative to that particular resource. If the field you select is (or is part of) an array, the server returns the selected portion of all elements in the array.

Here are some collection-level examples, which typically apply when listing resources such as buckets and objects:

Example	Effect
`items`	Returns all elements in the items array, including all fields in each element, but no other fields.
`etag,items`	Returns both the `etag` field and all elements in the items array.
`items/metadata/key`	Returns only the `key` field for all members of the `metadata` object, which is itself nested under the `items` array. Whenever a nested field is returned, the response includes the enclosing parent objects. The parent fields do not include any other child fields unless they are also selected explicitly.
`items(id,metadata/key)`	Returns only the values of the `id` and metadata `key` for each element in the items array.

Handling partial responses

After a server processes a valid request that includes the fields query parameter, it sends back an HTTP 200 OK status code, along with the requested data. If the fields query parameter has an error or is otherwise invalid, the server returns an HTTP 400 Bad Request status code, along with an error message telling the user what was wrong with their fields selection (for example, "Invalid field selection a/b").

Example

In a normal JSON API request to retrieve object metadata, Cloud Storage returns the full object resource in the response.

However, by using the fields parameter in your request, you can significantly reduce the amount of data returned in the response:

https://storage.googleapis.com/storage/v1/b/my-bucketT/o/my-object?fields=id,name,metadata/key1

Partial response: In response to the request above, the server sends back a response that contains only the kind information along with a pared-down items array that includes only the id, name, and the metadata/key property in each item, if present.

200 OK

{
  "id": "my-bucket/my-object.png/456456456456",
  "name": "my-object.png",
  "metadata": {
    "key1": "val1"
  }
}

Note that the response is a JSON object that includes only the selected fields and their enclosing parent objects.