api.proto in grpc-tools-1.6.0.pre1

- old
+ new

@@ -40,59 +40,66 @@
 option java_outer_classname = "ApiProto";
 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
   // indicates a breaking change and the minor version an additive,
   // non-breaking change. Both version numbers are signals to users
   // what to expect from different versions, and should be carefully
   // 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;
 
   // Source context for the protocol buffer service represented by this
   // 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.
   string name = 1;
 
@@ -113,13 +120,13 @@
 
   // The source syntax of this 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
 //   from the original method.
 //
@@ -127,11 +134,12 @@
 //   visibility) which is not set in the redeclared method will be
 //   inherited.
 //
 // - 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:
 //
 //     package google.acl.v1;
 //     service AccessControl {
@@ -191,10 +199,10 @@
 //         option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";
 //       }
 //       ...
 //     }
 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
   // are rooted.
   string root = 2;