From 09354db1434859a31a3c81abebcc4018d42f2715 Mon Sep 17 00:00:00 2001
From: Jisi Liu <jisi.liu@gmail.com>
Date: Tue, 18 Jul 2017 15:38:30 -0700
Subject: Merge from Google internal for 3.4 release

---
 src/google/protobuf/api.proto | 50 +++++++++++++++++++++++++------------------
 1 file changed, 29 insertions(+), 21 deletions(-)

(limited to 'src/google/protobuf/api.proto')

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
-- 
cgit v1.2.3