diff options
Diffstat (limited to 'src/google/protobuf/api.proto')
| -rw-r--r-- | src/google/protobuf/api.proto | 50 |
1 files changed, 29 insertions, 21 deletions
diff --git a/src/google/protobuf/api.proto b/src/google/protobuf/api.proto index 7c30e8b7..f37ee2fa 100644 --- a/src/google/protobuf/api.proto +++ b/src/google/protobuf/api.proto @@ -42,26 +42,33 @@ option java_multiple_files = true; option objc_class_prefix = "GPB"; option go_package = "google.golang.org/genproto/protobuf/api;api"; -// Api is a light-weight descriptor for a protocol buffer service. +// Api is a light-weight descriptor for an API Interface. +// +// Interfaces are also described as "protocol buffer services" in some contexts, +// such as by the "service" keyword in a .proto file, but they are different +// from API Services, which represent a concrete implementation of an interface +// as opposed to simply a description of methods and bindings. They are also +// sometimes simply referred to as "APIs" in other contexts, such as the name of +// this message itself. See https://cloud.google.com/apis/design/glossary for +// detailed terminology. message Api { - // The fully qualified name of this api, including package name - // followed by the api's simple name. + // The fully qualified name of this interface, including package name + // followed by the interface's simple name. string name = 1; - // The methods of this api, in unspecified order. + // The methods of this interface, in unspecified order. repeated Method methods = 2; - // Any metadata attached to the API. + // Any metadata attached to the interface. repeated Option options = 3; - // A version string for this api. If specified, must have the form - // `major-version.minor-version`, as in `1.10`. If the minor version - // is omitted, it defaults to zero. If the entire version field is - // empty, the major version is derived from the package name, as - // outlined below. If the field is not empty, the version in the - // package name will be verified to be consistent with what is - // provided here. + // A version string for this interface. If specified, must have the form + // `major-version.minor-version`, as in `1.10`. If the minor version is + // omitted, it defaults to zero. If the entire version field is empty, the + // major version is derived from the package name, as outlined below. If the + // field is not empty, the version in the package name will be verified to be + // consistent with what is provided here. // // The versioning schema uses [semantic // versioning](http://semver.org) where the major version number @@ -71,10 +78,10 @@ message Api { // chosen based on the product plan. // // The major version is also reflected in the package name of the - // API, which must end in `v<major-version>`, as in + // interface, which must end in `v<major-version>`, as in // `google.feature.v1`. For major versions 0 and 1, the suffix can // be omitted. Zero major versions must only be used for - // experimental, none-GA apis. + // experimental, non-GA interfaces. // // string version = 4; @@ -83,14 +90,14 @@ message Api { // message. SourceContext source_context = 5; - // Included APIs. See [Mixin][]. + // Included interfaces. See [Mixin][]. repeated Mixin mixins = 6; // The source syntax of the service. Syntax syntax = 7; } -// Method represents a method of an api. +// Method represents a method of an API interface. message Method { // The simple name of this method. @@ -115,9 +122,9 @@ message Method { Syntax syntax = 7; } -// Declares an API to be included in this API. The including API must -// redeclare all the methods from the included API, but documentation -// and options are inherited as follows: +// Declares an API Interface to be included in this interface. The including +// interface must redeclare all the methods from the included interface, but +// documentation and options are inherited as follows: // // - If after comment and whitespace stripping, the documentation // string of the redeclared method is empty, it will be inherited @@ -129,7 +136,8 @@ message Method { // // - If an http annotation is inherited, the path pattern will be // modified as follows. Any version prefix will be replaced by the -// version of the including API plus the [root][] path if specified. +// version of the including interface plus the [root][] path if +// specified. // // Example of a simple mixin: // @@ -193,7 +201,7 @@ message Method { // ... // } message Mixin { - // The fully qualified name of the API which is included. + // The fully qualified name of the interface which is included. string name = 1; // If non-empty specifies a path under which inherited HTTP paths |