|
|
|
|
# API style guidelines
|
|
|
|
|
|
|
|
|
|
Generally follow guidance at https://cloud.google.com/apis/design/, in
|
|
|
|
|
particular for proto3 as described at:
|
|
|
|
|
|
|
|
|
|
* https://cloud.google.com/apis/design/proto3
|
|
|
|
|
* https://cloud.google.com/apis/design/naming_convention
|
|
|
|
|
* https://developers.google.com/protocol-buffers/docs/style
|
|
|
|
|
|
|
|
|
|
In addition, the following conventions should be followed:
|
|
|
|
|
|
|
|
|
|
* The data plane APIs are primarily intended for machine generation and consumption.
|
|
|
|
|
It is expected that the management server is responsible for mapping higher
|
|
|
|
|
level configuration concepts to concrete API concepts. Similarly, static configuration
|
|
|
|
|
fragments may be generated by tools and UIs, etc. The APIs and tools used
|
|
|
|
|
to generate xDS configuration are beyond the scope of the definitions in this
|
|
|
|
|
repository.
|
|
|
|
|
|
|
|
|
|
* Use [wrapped scalar
|
|
|
|
|
types](https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto)
|
|
|
|
|
where there is a real need for the field to have a default value that does not
|
|
|
|
|
match the proto3 defaults (0/false/""). This should not be done for fields
|
|
|
|
|
where the proto3 defaults make sense. All things being equal, pick appropriate
|
|
|
|
|
logic, e.g. enable vs. disable for a `bool` field, such that the proto3
|
|
|
|
|
defaults work, but only where this doesn't result in API gymnastics.
|
|
|
|
|
|
|
|
|
|
* Always use plural field names for `repeated` fields, such as `filters`.
|
|
|
|
|
|
|
|
|
|
* Always use upper camel case names for message types and enum types without embedded
|
|
|
|
|
acronyms, such as `HttpRequest`.
|
|
|
|
|
|
|
|
|
|
* Prefer `oneof` selections to boolean overloads of fields, for example, prefer:
|
|
|
|
|
|
|
|
|
|
```proto
|
|
|
|
|
oneof path_secifier {
|
|
|
|
|
string simple_path = 1;
|
|
|
|
|
string regex_path = 2;
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
to
|
|
|
|
|
|
|
|
|
|
```proto
|
|
|
|
|
string path = 1;
|
|
|
|
|
bool path_is_regex = 2;
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This is more efficient, extendable and self-describing.
|
