|
| 1 | +// Protocol Buffers - Google's data interchange format |
| 2 | +// Copyright 2008 Google Inc. All rights reserved. |
| 3 | +// https://developers.google.com/protocol-buffers/ |
| 4 | +// |
| 5 | +// Redistribution and use in source and binary forms, with or without |
| 6 | +// modification, are permitted provided that the following conditions are |
| 7 | +// met: |
| 8 | +// |
| 9 | +// * Redistributions of source code must retain the above copyright |
| 10 | +// notice, this list of conditions and the following disclaimer. |
| 11 | +// * Redistributions in binary form must reproduce the above |
| 12 | +// copyright notice, this list of conditions and the following disclaimer |
| 13 | +// in the documentation and/or other materials provided with the |
| 14 | +// distribution. |
| 15 | +// * Neither the name of Google Inc. nor the names of its |
| 16 | +// contributors may be used to endorse or promote products derived from |
| 17 | +// this software without specific prior written permission. |
| 18 | +// |
| 19 | +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 20 | +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 21 | +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 22 | +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| 23 | +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 24 | +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| 25 | +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 26 | +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 27 | +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 28 | +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| 29 | +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 30 | + |
| 31 | +syntax = "proto3"; |
| 32 | + |
| 33 | +package google.protobuf; |
| 34 | + |
| 35 | +import "google/protobuf/source_context.proto"; |
| 36 | +import "google/protobuf/type.proto"; |
| 37 | + |
| 38 | +option csharp_namespace = "Google.Protobuf.WellKnownTypes"; |
| 39 | +option java_package = "com.google.protobuf"; |
| 40 | +option java_outer_classname = "ApiProto"; |
| 41 | +option java_multiple_files = true; |
| 42 | +option objc_class_prefix = "GPB"; |
| 43 | +option go_package = "google.golang.org/genproto/protobuf/api;api"; |
| 44 | + |
| 45 | +// Api is a light-weight descriptor for an API Interface. |
| 46 | +// |
| 47 | +// Interfaces are also described as "protocol buffer services" in some contexts, |
| 48 | +// such as by the "service" keyword in a .proto file, but they are different |
| 49 | +// from API Services, which represent a concrete implementation of an interface |
| 50 | +// as opposed to simply a description of methods and bindings. They are also |
| 51 | +// sometimes simply referred to as "APIs" in other contexts, such as the name of |
| 52 | +// this message itself. See https://cloud.google.com/apis/design/glossary for |
| 53 | +// detailed terminology. |
| 54 | +message Api { |
| 55 | + |
| 56 | + // The fully qualified name of this interface, including package name |
| 57 | + // followed by the interface's simple name. |
| 58 | + string name = 1; |
| 59 | + |
| 60 | + // The methods of this interface, in unspecified order. |
| 61 | + repeated Method methods = 2; |
| 62 | + |
| 63 | + // Any metadata attached to the interface. |
| 64 | + repeated Option options = 3; |
| 65 | + |
| 66 | + // A version string for this interface. If specified, must have the form |
| 67 | + // `major-version.minor-version`, as in `1.10`. If the minor version is |
| 68 | + // omitted, it defaults to zero. If the entire version field is empty, the |
| 69 | + // major version is derived from the package name, as outlined below. If the |
| 70 | + // field is not empty, the version in the package name will be verified to be |
| 71 | + // consistent with what is provided here. |
| 72 | + // |
| 73 | + // The versioning schema uses [semantic |
| 74 | + // versioning](http://semver.org) where the major version number |
| 75 | + // indicates a breaking change and the minor version an additive, |
| 76 | + // non-breaking change. Both version numbers are signals to users |
| 77 | + // what to expect from different versions, and should be carefully |
| 78 | + // chosen based on the product plan. |
| 79 | + // |
| 80 | + // The major version is also reflected in the package name of the |
| 81 | + // interface, which must end in `v<major-version>`, as in |
| 82 | + // `google.feature.v1`. For major versions 0 and 1, the suffix can |
| 83 | + // be omitted. Zero major versions must only be used for |
| 84 | + // experimental, non-GA interfaces. |
| 85 | + // |
| 86 | + // |
| 87 | + string version = 4; |
| 88 | + |
| 89 | + // Source context for the protocol buffer service represented by this |
| 90 | + // message. |
| 91 | + SourceContext source_context = 5; |
| 92 | + |
| 93 | + // Included interfaces. See [Mixin][]. |
| 94 | + repeated Mixin mixins = 6; |
| 95 | + |
| 96 | + // The source syntax of the service. |
| 97 | + Syntax syntax = 7; |
| 98 | +} |
| 99 | + |
| 100 | +// Method represents a method of an API interface. |
| 101 | +message Method { |
| 102 | + |
| 103 | + // The simple name of this method. |
| 104 | + string name = 1; |
| 105 | + |
| 106 | + // A URL of the input message type. |
| 107 | + string request_type_url = 2; |
| 108 | + |
| 109 | + // If true, the request is streamed. |
| 110 | + bool request_streaming = 3; |
| 111 | + |
| 112 | + // The URL of the output message type. |
| 113 | + string response_type_url = 4; |
| 114 | + |
| 115 | + // If true, the response is streamed. |
| 116 | + bool response_streaming = 5; |
| 117 | + |
| 118 | + // Any metadata attached to the method. |
| 119 | + repeated Option options = 6; |
| 120 | + |
| 121 | + // The source syntax of this method. |
| 122 | + Syntax syntax = 7; |
| 123 | +} |
| 124 | + |
| 125 | +// Declares an API Interface to be included in this interface. The including |
| 126 | +// interface must redeclare all the methods from the included interface, but |
| 127 | +// documentation and options are inherited as follows: |
| 128 | +// |
| 129 | +// - If after comment and whitespace stripping, the documentation |
| 130 | +// string of the redeclared method is empty, it will be inherited |
| 131 | +// from the original method. |
| 132 | +// |
| 133 | +// - Each annotation belonging to the service config (http, |
| 134 | +// visibility) which is not set in the redeclared method will be |
| 135 | +// inherited. |
| 136 | +// |
| 137 | +// - If an http annotation is inherited, the path pattern will be |
| 138 | +// modified as follows. Any version prefix will be replaced by the |
| 139 | +// version of the including interface plus the [root][] path if |
| 140 | +// specified. |
| 141 | +// |
| 142 | +// Example of a simple mixin: |
| 143 | +// |
| 144 | +// package google.acl.v1; |
| 145 | +// service AccessControl { |
| 146 | +// // Get the underlying ACL object. |
| 147 | +// rpc GetAcl(GetAclRequest) returns (Acl) { |
| 148 | +// option (google.api.http).get = "/v1/{resource=**}:getAcl"; |
| 149 | +// } |
| 150 | +// } |
| 151 | +// |
| 152 | +// package google.storage.v2; |
| 153 | +// service Storage { |
| 154 | +// rpc GetAcl(GetAclRequest) returns (Acl); |
| 155 | +// |
| 156 | +// // Get a data record. |
| 157 | +// rpc GetData(GetDataRequest) returns (Data) { |
| 158 | +// option (google.api.http).get = "/v2/{resource=**}"; |
| 159 | +// } |
| 160 | +// } |
| 161 | +// |
| 162 | +// Example of a mixin configuration: |
| 163 | +// |
| 164 | +// apis: |
| 165 | +// - name: google.storage.v2.Storage |
| 166 | +// mixins: |
| 167 | +// - name: google.acl.v1.AccessControl |
| 168 | +// |
| 169 | +// The mixin construct implies that all methods in `AccessControl` are |
| 170 | +// also declared with same name and request/response types in |
| 171 | +// `Storage`. A documentation generator or annotation processor will |
| 172 | +// see the effective `Storage.GetAcl` method after inherting |
| 173 | +// documentation and annotations as follows: |
| 174 | +// |
| 175 | +// service Storage { |
| 176 | +// // Get the underlying ACL object. |
| 177 | +// rpc GetAcl(GetAclRequest) returns (Acl) { |
| 178 | +// option (google.api.http).get = "/v2/{resource=**}:getAcl"; |
| 179 | +// } |
| 180 | +// ... |
| 181 | +// } |
| 182 | +// |
| 183 | +// Note how the version in the path pattern changed from `v1` to `v2`. |
| 184 | +// |
| 185 | +// If the `root` field in the mixin is specified, it should be a |
| 186 | +// relative path under which inherited HTTP paths are placed. Example: |
| 187 | +// |
| 188 | +// apis: |
| 189 | +// - name: google.storage.v2.Storage |
| 190 | +// mixins: |
| 191 | +// - name: google.acl.v1.AccessControl |
| 192 | +// root: acls |
| 193 | +// |
| 194 | +// This implies the following inherited HTTP annotation: |
| 195 | +// |
| 196 | +// service Storage { |
| 197 | +// // Get the underlying ACL object. |
| 198 | +// rpc GetAcl(GetAclRequest) returns (Acl) { |
| 199 | +// option (google.api.http).get = "/v2/acls/{resource=**}:getAcl"; |
| 200 | +// } |
| 201 | +// ... |
| 202 | +// } |
| 203 | +message Mixin { |
| 204 | + // The fully qualified name of the interface which is included. |
| 205 | + string name = 1; |
| 206 | + |
| 207 | + // If non-empty specifies a path under which inherited HTTP paths |
| 208 | + // are rooted. |
| 209 | + string root = 2; |
| 210 | +} |
0 commit comments