# 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).

* For enum types, if one of the enum values is used for most cases, make it the
  first enum value with `0` numeric value. Otherwise, define the first enum
  value like `TYPE_NAME_UNSPECIFIED = 0`, and treat it as an error. This design
  pattern forces developers to explicitly choose the correct enum value for
  their use case, and avoid misunderstanding of the default behavior.