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 java_generate_equals_and_hash = true; 43 option objc_class_prefix = "GPB"; 44 45 // Api is a light-weight descriptor for a protocol buffer service. 46 message Api { 47 48 // The fully qualified name of this api, including package name 49 // followed by the api's simple name. 50 string name = 1; 51 52 // The methods of this api, in unspecified order. 53 repeated Method methods = 2; 54 55 // Any metadata attached to the API. 56 repeated Option options = 3; 57 58 // A version string for this api. If specified, must have the form 59 // `major-version.minor-version`, as in `1.10`. If the minor version 60 // is omitted, it defaults to zero. If the entire version field is 61 // empty, the major version is derived from the package name, as 62 // outlined below. If the field is not empty, the version in the 63 // package name will be verified to be consistent with what is 64 // provided here. 65 // 66 // The versioning schema uses [semantic 67 // versioning](http://semver.org) where the major version number 68 // indicates a breaking change and the minor version an additive, 69 // non-breaking change. Both version numbers are signals to users 70 // what to expect from different versions, and should be carefully 71 // chosen based on the product plan. 72 // 73 // The major version is also reflected in the package name of the 74 // API, which must end in `v<major-version>`, as in 75 // `google.feature.v1`. For major versions 0 and 1, the suffix can 76 // be omitted. Zero major versions must only be used for 77 // experimental, none-GA apis. 78 // 79 // 80 string version = 4; 81 82 // Source context for the protocol buffer service represented by this 83 // message. 84 SourceContext source_context = 5; 85 86 // Included APIs. See [Mixin][]. 87 repeated Mixin mixins = 6; 88 89 // The source syntax of the service. 90 Syntax syntax = 7; 91 } 92 93 // Method represents a method of an api. 94 message Method { 95 96 // The simple name of this method. 97 string name = 1; 98 99 // A URL of the input message type. 100 string request_type_url = 2; 101 102 // If true, the request is streamed. 103 bool request_streaming = 3; 104 105 // The URL of the output message type. 106 string response_type_url = 4; 107 108 // If true, the response is streamed. 109 bool response_streaming = 5; 110 111 // Any metadata attached to the method. 112 repeated Option options = 6; 113 114 // The source syntax of this method. 115 Syntax syntax = 7; 116 } 117 118 // Declares an API to be included in this API. The including API must 119 // redeclare all the methods from the included API, but documentation 120 // and options are inherited as follows: 121 // 122 // - If after comment and whitespace stripping, the documentation 123 // string of the redeclared method is empty, it will be inherited 124 // from the original method. 125 // 126 // - Each annotation belonging to the service config (http, 127 // visibility) which is not set in the redeclared method will be 128 // inherited. 129 // 130 // - If an http annotation is inherited, the path pattern will be 131 // modified as follows. Any version prefix will be replaced by the 132 // version of the including API plus the [root][] path if specified. 133 // 134 // Example of a simple mixin: 135 // 136 // package google.acl.v1; 137 // service AccessControl { 138 // // Get the underlying ACL object. 139 // rpc GetAcl(GetAclRequest) returns (Acl) { 140 // option (google.api.http).get = "/v1/{resource=**}:getAcl"; 141 // } 142 // } 143 // 144 // package google.storage.v2; 145 // service Storage { 146 // rpc GetAcl(GetAclRequest) returns (Acl); 147 // 148 // // Get a data record. 149 // rpc GetData(GetDataRequest) returns (Data) { 150 // option (google.api.http).get = "/v2/{resource=**}"; 151 // } 152 // } 153 // 154 // Example of a mixin configuration: 155 // 156 // apis: 157 // - name: google.storage.v2.Storage 158 // mixins: 159 // - name: google.acl.v1.AccessControl 160 // 161 // The mixin construct implies that all methods in `AccessControl` are 162 // also declared with same name and request/response types in 163 // `Storage`. A documentation generator or annotation processor will 164 // see the effective `Storage.GetAcl` method after inherting 165 // documentation and annotations as follows: 166 // 167 // service Storage { 168 // // Get the underlying ACL object. 169 // rpc GetAcl(GetAclRequest) returns (Acl) { 170 // option (google.api.http).get = "/v2/{resource=**}:getAcl"; 171 // } 172 // ... 173 // } 174 // 175 // Note how the version in the path pattern changed from `v1` to `v2`. 176 // 177 // If the `root` field in the mixin is specified, it should be a 178 // relative path under which inherited HTTP paths are placed. Example: 179 // 180 // apis: 181 // - name: google.storage.v2.Storage 182 // mixins: 183 // - name: google.acl.v1.AccessControl 184 // root: acls 185 // 186 // This implies the following inherited HTTP annotation: 187 // 188 // service Storage { 189 // // Get the underlying ACL object. 190 // rpc GetAcl(GetAclRequest) returns (Acl) { 191 // option (google.api.http).get = "/v2/acls/{resource=**}:getAcl"; 192 // } 193 // ... 194 // } 195 message Mixin { 196 // The fully qualified name of the API which is included. 197 string name = 1; 198 199 // If non-empty specifies a path under which inherited HTTP paths 200 // are rooted. 201 string root = 2; 202 } 203
