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

What googleapis/googleapis actually contains, and who needs it

The repository description is explicit about the scope: "Public interface definitions of Google APIs." The README adds that the same proto3 interface definition is used for both the REST and RPC versions of an API. 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 lists the Google API client libraries, gRPC and the Google Cloud Client Libraries as the ways to access Google APIs.

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.

Building with Bazel and generating gRPC source with make

The repository root carries Bazel files (WORKSPACE, BUILD.bazel, .bazelrc) alongside a Makefile. The Makefile's header gives the syntax example `make OUTPUT=./output LANGUAGE=java`. 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." 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 Makefile turns Go 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 error message reads: "Go source files are not generated from this repository."

This is worth internalising before you plan anything. Go users get their generated protos from a separate repository. 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. The repository has no published GitHub 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.

A second limitation is toolchain coupling. The Makefile requires a grpc plugin binary at a path you supply, and a protoc on your PATH; a comment in the Makefile 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 Makefile names when it refuses LANGUAGE=go.

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-11-02, so the tree is current. The repository has no published GitHub 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 lists the Google API client libraries, gRPC and the Google Cloud Client Libraries as the ways to call Google APIs, and for Go the Makefile points to go-genproto. 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