View on GitHub
Frequently asked questions
Note: Have a question not answered here? Ask us on GitHub!
Why Protocol Buffers?
At Google, we define all of our APIs using Protocol Buffers (.proto files).
While we realize there are lots of other, newer ways of defining these
interfaces (e.g., OpenAPI, RAML, etc), we had to standardize on something and
since we're Google, we use protos.
This also leads to some very Google-specific ways of mapping proto RPCs to
RESTful URIs (google.api.http annotations). If you're not using protos, feel
free to follow the spirit of the API guidance since you won't be able to
follow the example snippets exactly as provided.
What's all this Googley stuff?
Originally, our API guidance was written by and for Googlers only. We're in the process of making this guidance more general to the world, but that's far from complete. If you see things like "Submit a CL" or "Talk to your PA lead", feel free to send pull requests to fix these oversights.
(CL stands for "Change List" which is sort of like a GitHub Pull Request, and PA stands for "Product Area" meaning things like "Google Maps" or "Google Workspace".)
I like most of these AIPs, but some make no sense for me. What do I do?
Sometimes guidance from AIPs makes lots of sense for Google (perhaps due to its size or scale) but no sense at all for others. This is much more common than we originally thought, so we added a way for sub-teams to override guidance that doesn't make sense for those teams.
If you want to adopt most of the AIPs but have a few that make no sense for your team, you can override those few and stick to just the ones that make sense for you.