1. Project Overview & Quickstart (googleapis/google-cloud-go)
Google Cloud Client Libraries for Go
Go packages for Google Cloud Platform services.
Installation
go get cloud.google.com/go/firestore@latest # Replace firestore with the package you want to use.NOTE: Some of these packages are under development, and may occasionally
make backwards-incompatible changes.
Supported APIs
For an updated list of all of our released APIs please see our
reference docs.
[Go Versions Supported](#supported-versions)
Our libraries are compatible with the two most recent major Go
releases, the same policy the Go
programming language follows. This means the currently supported versions are:
- Go 1.25
- Go 1.26
Authentication
By default, each client library will use Application Default Credentials
(ADC) to automatically configure the credentials used in calling the API endpoint.
When using the libraries in a Google Cloud Platform environment such as Compute
Engine, Kubernetes Engine, or App Engine, no additional authentication steps are
necessary. See Authentication methods at Google
and Authenticate for using client libraries
for more information.
client, err := storage.NewClient(ctx)For applications running elsewhere, such as your local development environment,
you can use the gcloud auth application-default login command from the
Google Cloud CLI to set user credentials in
your local filesystem. Application Default Credentials will automatically detect
these credentials. See Set up ADC for a local development
environment
for more information.
Alternately, you may need to provide an explicit path to your credentials. To authenticate
using a service account
key file, either set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path
to your key file, or programmatically passoption.WithCredentialsFile
to the NewClient function of the desired package. For example:
client, err := storage.NewClient(ctx, option.WithCredentialsFile("path/to/keyfile.json"))You can exert even more control over authentication by using the
credentials package to
create an auth.Credentials.
Then pass option.WithAuthCredentials
to the NewClient function:
creds, err := credentials.DetectDefault(&credentials.DetectOptions{...})
...
client, err := storage.NewClient(ctx, option.WithAuthCredentials(creds))Contributing
Contributions are welcome. Please, see the
CONTRIBUTING
document for details.
Please note that this project is released with a Contributor Code of Conduct.
By participating in this project you agree to abide by its terms.
See Contributor Code of Conduct
for more information.
Links
- Go on Google Cloud
- Getting started with Go on Google Cloud
- App Engine Quickstart
- Cloud Functions Quickstart
- Cloud Run Quickstart
2. Official Technical Reference & Guides (googleapis/googleapis.github.io)
Google APIs
The googleapis organization hosts tools,
technical articles, and issues related to Google API design and practice. It
also hosts client libraries for using many Google APIs from a variety of
supported languages.
Here we use Google APIs to refer to
networked APIs provided by Google services. Google APIs are developed as RPC
API services defined using
Protocol Buffers. These RPC
APIs are published directly as gRPC services and are made
available as
REST APIs
using
gRPC-HTTP/JSON Transcoding.
Most Google APIs are hosted on the googleapis.com domain, and Google API
specifications are published in
github.com/googleapis/googleapis. External
developers can use the published proto files to generate documentation and
client libraries or to guide their own API definitions.
API Design Guide
Google APIs use a common
API Design Guide that encourages a
simple and consistent API design philosophy. It also provides solutions to
common design issues, such as proper default values for enums and patterns for
long-running operations.
How to Call Google APIs
The easiest way to call a Google API is with a
Google Cloud Client Library:
All client libraries are fully open-source and are released under the Apache
License, Version 2.0.
For developers working in languages or environments that we don't support, we
provide instructions here for calling Google APIs in both
REST and
RPC forms:
API Client Tools
Google's API client libraries are produced with open source tools and
automation.
Generated API Clients (GAPICs)
Google's newest and most powerful APIs are built with gRPC,
an open-source RPC framework that grew from technologies developed at Google.
Many of the client libraries that we publish for these APIs are automatically
generated from API descriptions written in the
Protocol Buffers language.
All of our generators and related tools are open source and hosted in the
googleapis organization. To learn more about
them, see gapic-generators.
The googleapis organization also hosts
repositories that contain common code used by Google's generated and
handwritten client libraries. Details vary by language, but most provide
support for generally-needed features like paging and retry. Currently there is
one such library for each of the main languages that we support:
gax-dotnet,
gax-go,
gax-java,
gax-nodejs,
gax-php,
gax-python, and
gax-ruby. Note that we consider these
to be internal implementation details of our clients and reserve the right to
make changes, so if you choose to use them, be sure to refer to tagged
versions.
The API Discovery Format
Before gRPC, Google APIs were published primarily as REST APIs and described
with the
Google API Discovery Service. Now
via
gRPC-HTTP/JSON Transcoding,
many of Google's gRPC APIs are also available as HTTP/JSON APIs and described
by the API Discovery Service. These HTTP/JSON APIs have been supported by a
previous generation of client libraries and code generators based on the API
Discovery Service. Google API support teams published support for several
programming languages
(Java,
Python,
PHP,
.NET,
Javascript,
Ruby,
Go,
Node.js, and
Objective-C).
We also currently have experimental support for
Swift. Support for
other languages has been developed by external developers
(Rust) and other groups within
Google (Dart).
Currently, we are not aware of any other API provider using the API Discovery
Format. In contrast, a large community of API producers and consumers has grown
around the
OpenAPI Specification (formerly
known as Swagger), with many community tools emerging for
working with OpenAPI descriptions of REST APIs.
OpenAPI
We recommend using OpenAPI and OpenAPI-based tools for working with Google's
REST APIs. Several tools for converting Google Discovery Format to OpenAPI have
been published:
- google-discovery-to-swagger,
an MIT-licensed open source script for converting Google Discovery format
into Swagger 2.0. - API Spec Converter, an
online converter from LucyBot. - The API Transformer from
APIMatic.
Google's OpenAPI tools include
gnostic, a front-end for OpenAPI tools
that reads OpenAPI descriptions, puts them in an efficient binary
representation, and allows efficient plugins and standalone tools to be easily
written in any programming language with Protocol Buffer support.
Issues
If you have feedback or questions regarding API design or methodology, please
file an issue in the
googleapis.github.io issues area.
For specific tool questions, please file an issue on the corresponding
repository. We look forward to hearing from you!