Request endpoints

This page explains the different request endpoints you can use to access Cloud Storage. Cloud Storage supports HTTP/1.1, HTTP/2, and HTTP/3 protocols. An endpoint is the location where Cloud Storage can be accessed, written as a URL.

Typical API requests

JSON API

When making JSON API requests directly to Cloud Storage, use the following endpoints:

  • For general JSON API requests, excluding object uploads, use the following endpoint, replacing PATH_TO_RESOURCE with the appropriate value:

    https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE

  • For JSON API object uploads, use the following endpoint, replacing BUCKET_NAME with the appropriate value:

    https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o

  • For batched requests, use the following endpoint, replacing PATH_TO_RESOURCE with the appropriate value:

    https://storage.googleapis.com/batch/storage/v1/PATH_TO_RESOURCE

  • Optionally, for JSON API object downloads, you can use the following endpoint, replacing BUCKET_NAME and OBJECT_NAME with the appropriate values:

    https://storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

JSON API endpoints only accept HTTPS requests.

XML API

When making XML API requests directly to Cloud Storage, use the virtual hosted-style or path-style endpoint, replacing BUCKET_NAME and OBJECT_NAME with the appropriate values:

  • Virtual hosted-style endpoint: 

    https://BUCKET_NAME.storage.googleapis.com/OBJECT_NAME

  • Path-style endpoint: 

    https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

XML API endpoints support secure sockets layer (SSL) encryption, which means you can use either HTTP or HTTPS. Using HTTPS is recommended, especially if you authenticate to Cloud Storage using OAuth 2.0.

gRPC

You can use gRPC, a high performance, open source universal RPC framework developed by Google, to interact with Cloud Storage. gRPC clients connect to a service endpoint. For Google Cloud services like Cloud Storage, this is typically a DNS address on the googleapis.com domain (for example, storage.googleapis.com) and uses standard secure ports such as 443. Using gRPC can provide improved performance and efficient streaming capabilities.

To use gRPC to interact with Cloud Storage, you need to enable it on Cloud Client Libraries.

Enable gRPC on a client library using one of the following supported languages:

For connections through a proxy, see the Troubleshooting topic for recommended practices.

Encoding URL path parts

In addition to general considerations for bucket naming and object naming, to ensure compatibility across Cloud Storage tools, you should encode the following characters when they appear in either the object name or query string of a request URL:

!, #, $, &, ', (, ), *, +, ,, /, :, ;, =, ?, @, [, ], and space characters.

For example, if you send a JSON API GET request for the object named foo??bar in the bucket example-bucket, then your request URL should be:

GET https://storage.googleapis.com/storage/v1/b/example-bucket/o/foo%3f%3fbar

Note that not all of the listed characters must be encoded in every scenario. Additionally, encoding is typically handled for you by client libraries, such as the Cloud Storage Client Libraries, so you can pass the raw object name when using such tools.

For more information about using percent-encoding, see Section 3.3 Path in RFC 3986.

Google Cloud console endpoints

When using the Google Cloud console, you access different resources using the following URLs:

Resource URL
Bucket list for a project https://console.cloud.google.com/storage/browser?project=PROJECT_ID
Object list for a bucket https://console.cloud.google.com/storage/browser/BUCKET_NAME
Details for an object https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME
Data for an object See Authenticated browser downloads

gcloud endpoints

gcloud storage commands use JSON API endpoints. Endpoint usage is managed on your behalf by the gcloud CLI.

Client library endpoints

Cloud Storage client libraries manage request endpoints automatically. Optionally, you can set the request endpoint manually. This can be useful when you want to use a specific endpoint, or for testing, such as when you want to use a local emulator:

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries. 

namespace g = ::google::cloud;
namespace gcs = ::google::cloud::storage;
[](std::string const& bucket_name, std::string const& object_name) {
  // NOTE: the CLOUD_STORAGE_EMULATOR_HOST environment variable overrides any
  //     value provided here.
  auto client = gcs::Client(g::Options{}.set<gcs::RestEndpointOption>(
      "https://storage.googleapis.com"));
  PerformSomeOperations(client, bucket_name, object_name);
}

C#

For more information, see the Cloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries. 


using Google.Cloud.Storage.V1;
using System;

public class SetClientEndpointSample
{
    public StorageClient SetClientEndpoint(string endpoint) => new StorageClientBuilder
    {
        BaseUri = endpoint
    }.Build();
}

Go

For more information, see the Cloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries. 

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/storage"
	"google.golang.org/api/option"
)

// setClientEndpoint sets the request endpoint.
func setClientEndpoint(w