You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
71 lines
2.6 KiB
71 lines
2.6 KiB
# 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: |
|
|
|
* For protos that are [frozen](https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/v2_overview#status), |
|
the following guidelines are followed: |
|
|
|
* Fields should not be renumbered or have their types changed. This is standard proto development |
|
procedure. |
|
* Fields should not be **renamed**. This is stricter than standard proto development procedure |
|
in the sense that it does not break binary wire format. However, it **does** break loading |
|
of YAML/JSON into protos as well as text protos. Since we consider YAML/JSON to be first class |
|
inputs, we must not change field names. |
|
* If fields are deleted, the following syntax should be put in their place: |
|
|
|
```proto |
|
reserved <field index>; |
|
``` |
|
|
|
E.g., |
|
|
|
```proto |
|
reserved 15; |
|
``` |
|
|
|
* 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. |
|
|
|
* To represent percentage values, use the Percent message type defined in [api/base.proto](api/base.proto).
|
|
|