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 31syntax = "proto3"; 32 33package google.protobuf; 34 35import "google/protobuf/source_context.proto"; 36import "google/protobuf/type.proto"; 37 38option csharp_namespace = "Google.Protobuf.WellKnownTypes"; 39option java_package = "com.google.protobuf"; 40option java_outer_classname = "ApiProto"; 41option java_multiple_files = true; 42option java_generate_equals_and_hash = true; 43option objc_class_prefix = "GPB"; 44 45// Api is a light-weight descriptor for a protocol buffer service. 46message 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. 94message 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// } 195message 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