Cloud Storage JSON API overview

The Cloud Storage JSON API is a simple, JSON-backed interface foraccessing and manipulating Cloud Storage projects in a programmatic way. Itis fully compatible with theCloud Storage Client Libraries.

The JSON API is intended for software developers. To use it youshould be familiar with web programming and be comfortable creatingapplications that consume web services through HTTP requests. If this does notdescribe you, consider one of the following 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 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.

The current release of the JSON API isv1.

Partial response

By default, when Cloud Storage sends a resource in a response, itsends the full representation of the resource. For better performance, you canask Cloud Storage to send only the fields you specify. This iscalled apartial response.

To request a partial response, use thefields request parameter to specifythe fields you want returned. You can use this parameter with any requestthat returns response data. Thefields parameter only affects the responsedata; it does not affect the data that you need to send, if any. To reduce theamount of data you send when modifying resources, use aPATCH request.

Note: As with all query parameter values, thefields parameter value must beURL encoded. For better readability, the examples in this page omit theencoding.

Syntax summary

The format of thefields request parameter value is loosely based on XPathsyntax. When using thefields parameter, follow these guidelines:

  • Use a comma-separated list to return multiple fields.

    For example,fields=name,generation,size.

  • Usea/b to return a fieldb that is nested within fielda; usea/b/cto return a fieldc nested withinb.

    For example,fields=metadata/key1.

  • By default, if your request specifies particular fields, the server returnsthe objects or array elements in their entirety.Use a sub-selector to requesta set of specific sub-fields of arrays or objects by placing expressions inparentheses.

    For example:fields=items(id,metadata/key1) returns only the item ID andthekey1 custom metadata for each element in the items array. You can alsospecify a single sub-field, wherefields=items(id) is equivalent tofields=items/id.

  • Each field specified infields is relative to the root of the response. Soif you are performing an operation to list objects, the response is acollection that includes as part of it an array of objects. If you areperforming an operation that returns a single object or bucket, fields arespecified relative to that particular resource. If the field you select is(or is part of) an array, the server returns the selected portion of allelements in the array.

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

ExampleEffect
itemsReturns all elements in the items array, including all fields in each element, but no other fields.
etag,itemsReturns both theetag field and all elements in the items array.
items/metadata/keyReturns only thekey field for all members of themetadata object, which is itself nested under theitems 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 theid and metadatakey for each element in the items array.

Handling partial responses

After a server processes a valid request that includes thefields queryparameter, it sends back an HTTP200 OK status code, along with the requesteddata. If thefields query parameter has an error or is otherwise invalid, theserver returns an HTTP400 Bad Request status code, along with an errormessage telling the user what was wrong with their fields selection (forexample,"Invalid field selection a/b").

Example

In a normalJSON API request to retrieve object metadata,Cloud Storage returns thefull object resource in the response.

However, by using thefields parameter in your request, you can significantlyreduce 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 aresponse that contains only the kind information along with a pared-down itemsarray that includes only the id, name, and the metadata/key property ineach 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 fieldsand their enclosing parent objects.

Partial updates

You can avoid sending unnecessary data when modifying resources. To sendupdated values for specific fields of a resource's metadata, instead ofreplacing the resource's metadata in its entirety, use the HTTPPATCH verb.

The following Cloud Storage resources supportPATCH requests:

Semantics of a patch request

The body of thePATCH request includes only the resource fields you want tomodify. When you specify a field, you must include any enclosing parent objects,just as the enclosing parents are returned with a partial response. The modifieddata you send is merged into the data for the parent object, if there is one.

  • Add: To add a field that doesn't already exist, specify the new field andits value.
  • Modify: To change the value of an existing field, specify the field andset it to the new value.
  • Delete: Although many fields cannot be deleted, some, such asObject Lifecycle Management configurations andcustom metadata,can be deleted. To do so, specify the field and set it tonull. Forexample,"metadata": null.

Note about arrays: Patch requests that contain arrays replace the existingarray with the one you provide. You cannot modify, add, or delete items in anarray in a piecemeal fashion.

Handling the response to a patch

After processing a validPATCH request, the API returns a200 OK HTTPresponse code along with the complete representation of the modified resource.

The patch request returns the entire resource representation unless you use thefields parameter to reduce the amount of data it returns.

If a patch request results in a new resource state that is syntactically orsemantically invalid, the server returns a400 Bad Request or422 Unprocessable Entity HTTP status code, and the resource state remainsunchanged. For example, if you attempt to delete the value for a requiredfield, the server returns an error.

Alternate notation when PATCH HTTP verb is not supported

If your firewall does not allow HTTPPATCH requests, then you can send an HTTPPOST request and set the override header toPATCH, as shown below:

POST https://storage.googleapis.com/...X-HTTP-Method-Override: PATCH...

Example

This example shows a simple patch request to update only the metadata of aCloud Storage JSON API object. The object also has an id, a name,generation, and many other fields, but this request only sends themetadatafield, since that's the only field being modified:

PATCH https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAMEAuthorization: BearerOAUTH2_TOKENContent-Type: application/json{  "metadata": {"NEW_KEY" : "NEW_VALUE"}}

Response:

200 OK
{"id":"OBJECT_ID","name":"OBJECT_NAME","bucket":"BUCKET_NAME","metadata":{"EXISTING_KEY":"EXISTING_VALUE","NEW_KEY":"NEW_VALUE"},...}

The server returns a200 OK status code, along with the full representationof the updated resource. Since only themetadata field was included in thepatch request, that's the only value that is different from before.

Query parameters

To use query parameters with a request, add?, the name of the query parameter,and the desired value to the end of the request URL. You can use this syntaxwith all JSON query parameters:

https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?QUERY_PARAMETER=VALUE

For an example, seeAccessing noncurrent object versions.

You can specify multiple query parameters in the same request by using an&between each one:

https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?QUERY_PARAMETER=VALUE&QUERY_PARAMETER_2=VALUE_2

For an example, see theUploading objects page.

What's next

Try it for yourself

If you're new to Google Cloud, create an account to evaluate how Cloud Storage performs in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Try Cloud Storage free

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-12-15 UTC.