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