diff options
Diffstat (limited to 'src/google/protobuf/api.proto')
-rw-r--r-- | src/google/protobuf/api.proto | 107 |
1 files changed, 101 insertions, 6 deletions
diff --git a/src/google/protobuf/api.proto b/src/google/protobuf/api.proto index f368c24d..41cd5131 100644 --- a/src/google/protobuf/api.proto +++ b/src/google/protobuf/api.proto @@ -34,14 +34,15 @@ package google.protobuf; import "google/protobuf/source_context.proto"; import "google/protobuf/type.proto"; -option java_multiple_files = true; -option java_outer_classname = "ApiProto"; option java_package = "com.google.protobuf"; +option java_outer_classname = "ApiProto"; +option java_multiple_files = true; +option java_generate_equals_and_hash = true; option objc_class_prefix = "GPB"; - // Api is a light-weight descriptor for a protocol buffer service. message Api { + // The fully qualified name of this api, including package name // followed by the api's simple name. string name = 1; @@ -73,18 +74,22 @@ message Api { // be omitted. Zero major versions must only be used for // experimental, none-GA apis. // - // See also: [design doc](http://go/api-versioning). - // - // string version = 4; // Source context for the protocol buffer service represented by this // message. SourceContext source_context = 5; + + // Included APIs. See [Mixin][]. + repeated Mixin mixins = 6; + + // The source syntax of the service. + Syntax syntax = 7; } // Method represents a method of an api. message Method { + // The simple name of this method. string name = 1; @@ -102,4 +107,94 @@ message Method { // Any metadata attached to the method. repeated Option options = 6; + + // 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: +// +// - If after comment and whitespace stripping, the documentation +// string of the redeclared method is empty, it will be inherited +// from the original method. +// +// - Each annotation belonging to the service config (http, +// 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. +// +// Example of a simple mixin: +// +// package google.acl.v1; +// service AccessControl { +// // Get the underlying ACL object. +// rpc GetAcl(GetAclRequest) returns (Acl) { +// option (google.api.http).get = "/v1/{resource=**}:getAcl"; +// } +// } +// +// package google.storage.v2; +// service Storage { +// // (-- see AccessControl.GetAcl --) +// rpc GetAcl(GetAclRequest) returns (Acl); +// +// // Get a data record. +// rpc GetData(GetDataRequest) returns (Data) { +// option (google.api.http).get = "/v2/{resource=**}"; +// } +// } +// +// Example of a mixin configuration: +// +// apis: +// - name: google.storage.v2.Storage +// mixins: +// - name: google.acl.v1.AccessControl +// +// The mixin construct implies that all methods in `AccessControl` are +// also declared with same name and request/response types in +// `Storage`. A documentation generator or annotation processor will +// see the effective `Storage.GetAcl` method after inherting +// documentation and annotations as follows: +// +// service Storage { +// // Get the underlying ACL object. +// rpc GetAcl(GetAclRequest) returns (Acl) { +// option (google.api.http).get = "/v2/{resource=**}:getAcl"; +// } +// ... +// } +// +// Note how the version in the path pattern changed from `v1` to `v2`. +// +// If the `root` field in the mixin is specified, it should be a +// relative path under which inherited HTTP paths are placed. Example: +// +// apis: +// - name: google.storage.v2.Storage +// mixins: +// - name: google.acl.v1.AccessControl +// root: acls +// +// This implies the following inherited HTTP annotation: +// +// service Storage { +// // Get the underlying ACL object. +// rpc GetAcl(GetAclRequest) returns (Acl) { +// option (google.api.http).get = "/v2/acls/{resource=**}:getAcl"; +// } +// ... +// } +message Mixin { + // The fully qualified name of the API which is included. + string name = 1; + + // If non-empty specifies a path under which inherited HTTP paths + // are rooted. + string root = 2; } |