googleapis/googleapis: the proto definitions behind Google's REST and gRPC APIs

What googleapis/googleapis actually contains, and who needs it

The README is explicit about the scope: this repository contains "the original interface definitions of public Google APIs that support both REST and gRPC protocols." That single sentence rules out most of what people search for. There is no runtime, no HTTP client, no authentication helper and no generated code checked in for you to import. What is here is proto3, plus the configuration that Google's own tooling consumes.

The audience is narrow but real. If you are writing a code generator, a documentation pipeline, an API gateway that needs the full method surface of a Google service, or a policy checker that validates calls against the declared contract, the definitions in this repository are the source of truth. If you are writing an application that calls Cloud Storage or the OAuth token endpoint, this is the wrong layer entirely. The README directs application developers to the Google API client libraries, gRPC, or the Google Cloud Client Libraries, and the repository's own Discussions section tells you to raise issues about client libraries in the repositories associated with each area rather than here.

The topics list on the repository is just protocol-buffers, which is an accurate signal of what you get. The primary language is Starlark, which reflects the Bazel build files rather than the content: the payload is .proto files organised under google/.

How the directory layout encodes API identity

The README states that the repository "uses a directory hierarchy that reflects the Google API product structure," with one root directory per API and one subdirectory per major version. The proto package name matches the directory exactly. That is a design decision with consequences: the import path in a proto file and the generated namespace in most languages are derived from the same string, so a misplaced file breaks both at once.

The README also notes that the major version indicates a breaking change to the API. In practice this means you should pin to a version directory rather than tracking master, because a new major version directory can appear without the old one changing meaning, and the generated namespaces will differ.

Alongside the API directories sit configuration files for the GAPIC toolkit, visible in the repository as the gapic/ directory. Those files describe how to generate idiomatic client surfaces from the same protos, which is how the per-language client libraries are produced elsewhere. There is also a preview/ directory and a grafeas/ directory at the top level, plus generator-versions.json, which pins the generator toolchain the repository expects.

Building with Bazel and generating gRPC source with make

The repository offers two build paths, and they do different things. Bazel is described as the recommended way to build the API client libraries, requiring Bazel >= 4.2.2. The README gives these commands, which build and test everything in the workspace:

bazel build //...
bazel test //...

Scoping to a single API version is the more useful form for day-to-day work, and the README shows the pattern with an example library path:

bazel build //google/example/library/v1/...

The README states that Bazel packages exist in all the libraries for Java, Go, Python, Ruby, Node.js, PHP and C#. A language-specific target is also documented, for example the Java package for one library:

bazel build //google/example/library/v1:google-cloud-example-library-v1-java

The second path is the Makefile, which the README introduces as `make LANGUAGE=xxx all`. It is not a build system for a usable library. The Makefile's own header comment says it "does not compile the generated code into final libraries that can be directly used with application code," and the README repeats that the Makefile "is only intended to generate source code for the entire repository." The variables you set are OUTPUT (default ./gens), LANGUAGE (default cpp), GRPCPLUGIN (default /usr/local/bin/grpc_$(LANGUAGE)_plugin), PROTOINCLUDE (default /usr/local/include) and PROTOC (default protoc). The rule invokes protoc with --proto_path, --$(LANGUAGE)_out and --grpc_out, plus --plugin=protoc-gen-grpc. Note the default suffix is pb.cc, which is a C++ assumption baked into the dependency list.

Go is the exception, and the Makefile enforces it

The README devotes a short subsection to Go and the Makefile turns it into a hard stop. Attempting `make LANGUAGE=go all` fails immediately, because the Makefile contains an explicit error rule for that case, with the message pointing at github.com/google/go-genproto. The README explains why: "It is difficult to generate Go gRPC source code from this repository, since Go has different directory structure."

This is worth internalising before you plan anything. Go users get their generated protos from a separate repository, and the Bazel targets here for Go are a different mechanism from the Makefile path. If your pipeline assumes one repository produces all language bindings uniformly, that assumption is wrong for Go specifically.

Where this repository is the wrong tool

The clearest failure mode is treating it as a dependency. There are no retrieved releases, so there is no versioned artifact to pin in a package manager; you consume it by cloning or vendoring, and you carry the whole tree unless you prune it. The README's Discussions note is effectively a boundary marker: issues about client libraries, gRPC or Cloud Client Libraries belong in their own repositories, not here.

A second limitation is toolchain coupling. The Makefile requires a grpc plugin binary at a path you supply, and a protoc on your PATH; the README warns that if protoc is not in the PATH you must modify the file. Generating for a language other than C++ means overriding the suffix assumption and supplying the right plugin, and the Makefile's dependency list is built by scanning for .proto files, so a partial checkout can produce a confusing target set.

A third is the versioning contract itself. Because the major version signals breaking change, code generated from two different version directories will not interoperate at the type level even when the underlying service is the same product. Anything that aggregates across versions has to handle that explicitly.

Alternatives and how they differ in approach

The most direct alternative for Go is github.com/google/go-genproto, which the README and the Makefile both name. The difference is structural rather than philosophical: go-genproto exists because Go's import paths and directory conventions do not map onto the product-and-version hierarchy used here, so the generated Go packages are maintained in a repository shaped for Go's tooling.

For everything else, the alternative is to skip the protos entirely and use a published client library. The README lists three access routes: JSON over HTTP via the Google API client library or third-party libraries, Protocol Buffers over gRPC, and the Google Cloud Client Libraries, which the README describes as based on gRPC for performance with an idiomatic client surface. Choosing one of those means you inherit a maintained surface and lose the ability to inspect or regenerate the contract yourself. That trade is the real decision: this repository is for when you need the definition, not the client.

Licence, maintenance and the cost of tracking master

The repository is licensed Apache-2.0, and the LICENSE file is at the top level. Apache-2.0 is a permissive licence with an explicit patent grant and notice requirements; if you redistribute generated code or the proto files themselves, the notice obligations apply. That is a summary of what the licence identifier means, not legal advice, and the terms in the LICENSE file govern.

The last push was on 2026-09-21, so the tree is current. There are no retrieved releases, which means there is no changelog-driven upgrade path: you upgrade by moving your checkout forward, and the only signal of a breaking change is a new major version directory. Budget for that. If you generate from this repository, pin a commit and regenerate deliberately rather than following master, because the proto package names and the directory layout are the same string and a change to either ripples into every generated namespace.

Editorial conclusion

Adopt this repository if you generate code or documentation from Google's own proto3 definitions, or if you need to inspect a service's contract before writing against it. Do not adopt it if you want a callable client: the README points to the per-language client library repositories under github.com/googleapis instead, and for Go it points to go-genproto because the directory layout here does not match Go's. Before committing, verify that the API version directory you need actually exists under google/, check the gapic/ configuration for the API, and confirm that your protoc and grpc plugin versions can compile the files you selected, since the Makefile requires a grpc_$(LANGUAGE)_plugin at a path you set yourself.

Frequently asked questions

Official sources

1. googleapis/googleapis on GitHub
2. Issues
3. License: Apache-2.0
4. README