File and directory structure
A consistent file and directory structure, while making minimal difference technically, makes API surface definitions easier for users and reviewers to read.
Note: The following guidance applies to APIs defined in protocol buffers, such as those used throughout Google. While the spirit of this guidance applies to APIs defined using other specification languages or formats, some of the particular recommendations might be irrelevant.
APIs defined in protocol buffers must define each individual API in a single package, which must end in a version component. For example:
syntax = "proto3"; package google.cloud.translation.v3;
Google APIs must reside in a directory that matches the protocol buffer
package directive. For example, the package above dictates that the directory
It is often useful to divide API definitions into multiple files. File names
APIs should have an obvious "entry" file, generally named after the API
itself. An API with a small number of discrete services (Google Cloud Pub/Sub's
Subscriber is a good example) may have a separate entry
file per service.
APIs with only one file should use a filename corresponding to the name of the API.
Bear in mind that the file names often become module names in client libraries,
and customers use them in
use statements. Therefore, choosing a
descriptive and language keyword-free filename does matter. For example, a file
import.proto may be problematic in Python.
Note: The version must not be used as a filename, because this creates
bizarre imports in client libraries. Filenames such as
v1beta1.proto are prohibited.
Individual files should place higher level and more important definitions before lower level and less important definitions.
In a proto file, components should be in the following order, and each of these should be separated by a blank line:
- Copyright and license notice (if applicable).
- The proto
- The proto
importstatements, in alphabetical order.
- Any file-level
- Methods should be grouped by the resource they impact, and standard methods should precede custom methods.
messagedefinitions. A parent resource must be defined before its child resources.
- The RPC request and response
messagedefinitions, in the same order of the corresponding methods. Each request message must precede its corresponding response message (if any).
- Any remaining
- Any top-level
Protocol buffers ships with annotations to declare the package or namespace
(depending on the vocabulary of the target language) of the generated files.
For example, setting
csharp_namespace will override the
inferred package name.
When defining APIs, the following rules apply:
java_packageannotation must be set. The correct value is usually the proto package with the appropriate TLD prefixed. Example:
java_multiple_filesannotation must be set to
java_outer_classnameannotation must be set, and should be set to the name of the proto filename, in
- Other languages
- Package or namespace directives for other languages must be set either in every file in the proto package, or none of them. If they are set, the values must be identical in every file.
Important: While other languages have sensible defaults, be aware that adding this annotation (with a value not equivalent to the default) constitutes a breaking change in that language. When releasing protos, be sure that omissions are intentional.
- 2019-11-18: Added guidance on the packaging annotations.