Skip to content
AEP

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.

Syntax

APIs defined in protocol buffers must use proto3 syntax.

Single package

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 example.cloud.translation.v3;

APIs must reside in a directory that matches the protocol buffer package directive. For example, the package above dictates that the directory be example/cloud/translation/v3.

File names

It is often useful to divide API definitions into multiple files. File names must use snake_case.

APIs should have an obvious “entry” file, generally named after the API itself. An API with a small number of discrete services may have a separate entry file per service.

APIs with only one file should use a filename corresponding to the name of the API.

API service definitions and associated RPC request and response message definitions should be defined in the same file.

Bear in mind that the file names often become module names in client libraries, and customers use them in import or use statements. Therefore, choosing a descriptive and language keyword-free filename does matter. For example, a file called import.proto may be problematic in Python.

File layout

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 syntax statement.
  • The proto package statement.
  • Any import statements, in alphabetical order.
  • Any file-level option statements.
  • Any service definitions.
    • Methods should be grouped by the resource they impact, and standard methods should precede custom methods.
  • Resource message definitions. A parent resource must be defined before its child resources.
  • The RPC request and response message definitions, in the same order of the corresponding methods. Each request message must precede its corresponding response message (if any).
  • Any remaining message definitions.
  • Any top-level enum definitions.