codekingpro/portable-devtools

1// Copyright 2026 Google LLC2//3// Licensed under the Apache License, Version 2.0 (the "License");4// you may not use this file except in compliance with the License.5// You may obtain a copy of the License at6//7//     http://www.apache.org/licenses/LICENSE-2.08//9// Unless required by applicable law or agreed to in writing, software10// distributed under the License is distributed on an "AS IS" BASIS,11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.12// See the License for the specific language governing permissions and13// limitations under the License.14 15syntax = "proto3";16 17package google.api;18 19option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations";20option java_multiple_files = true;21option java_outer_classname = "HttpProto";22option java_package = "com.google.api";23option objc_class_prefix = "GAPI";24 25// Defines the HTTP configuration for an API service. It contains a list of26// [HttpRule][google.api.HttpRule], each specifying the mapping of an RPC method27// to one or more HTTP REST API methods.28message Http {29  // A list of HTTP configuration rules that apply to individual API methods.30  //31  // **NOTE:** All service configuration rules follow "last one wins" order.32  repeated HttpRule rules = 1;33 34  // When set to true, URL path parameters will be fully URI-decoded except in35  // cases of single segment matches in reserved expansion, where "%2F" will be36  // left encoded.37  //38  // The default behavior is to not decode RFC 6570 reserved characters in multi39  // segment matches.40  bool fully_decode_reserved_expansion = 2;41}42 43// gRPC Transcoding44//45// gRPC Transcoding is a feature for mapping between a gRPC method and one or46// more HTTP REST endpoints. It allows developers to build a single API service47// that supports both gRPC APIs and REST APIs. Many systems, including [Google48// APIs](https://github.com/googleapis/googleapis),49// [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC50// Gateway](https://github.com/grpc-ecosystem/grpc-gateway),51// and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature52// and use it for large scale production services.53//54// `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies55// how different portions of the gRPC request message are mapped to the URL56// path, URL query parameters, and HTTP request body. It also controls how the57// gRPC response message is mapped to the HTTP response body. `HttpRule` is58// typically specified as an `google.api.http` annotation on the gRPC method.59//60// Each mapping specifies a URL path template and an HTTP method. The path61// template may refer to one or more fields in the gRPC request message, as long62// as each field is a non-repeated field with a primitive (non-message) type.63// The path template controls how fields of the request message are mapped to64// the URL path.65//66// Example:67//68//     service Messaging {69//       rpc GetMessage(GetMessageRequest) returns (Message) {70//         option (google.api.http) = {71//             get: "/v1/{name=messages/*}"72//         };73//       }74//     }75//     message GetMessageRequest {76//       string name = 1; // Mapped to URL path.77//     }78//     message Message {79//       string text = 1; // The resource content.80//     }81//82// This enables an HTTP REST to gRPC mapping as below:83//84// - HTTP: `GET /v1/messages/123456`85// - gRPC: `GetMessage(name: "messages/123456")`86//87// Any fields in the request message which are not bound by the path template88// automatically become HTTP query parameters if there is no HTTP request body.89// For example:90//91//     service Messaging {92//       rpc GetMessage(GetMessageRequest) returns (Message) {93//         option (google.api.http) = {94//             get:"/v1/messages/{message_id}"95//         };96//       }97//     }98//     message GetMessageRequest {99//       message SubMessage {100//         string subfield = 1;101//       }102//       string message_id = 1; // Mapped to URL path.103//       int64 revision = 2;    // Mapped to URL query parameter `revision`.104//       SubMessage sub = 3;    // Mapped to URL query parameter `sub.subfield`.105//     }106//107// This enables a HTTP JSON to RPC mapping as below:108//109// - HTTP: `GET /v1/messages/123456?revision=2&sub.subfield=foo`110// - gRPC: `GetMessage(message_id: "123456" revision: 2 sub:111// SubMessage(subfield: "foo"))`112//113// Note that fields which are mapped to URL query parameters must have a114// primitive type or a repeated primitive type or a non-repeated message type.115// In the case of a repeated type, the parameter can be repeated in the URL116// as `...?param=A&param=B`. In the case of a message type, each field of the117// message is mapped to a separate parameter, such as118// `...?foo.a=A&foo.b=B&foo.c=C`.119//120// For HTTP methods that allow a request body, the `body` field121// specifies the mapping. Consider a REST update method on the122// message resource collection:123//124//     service Messaging {125//       rpc UpdateMessage(UpdateMessageRequest) returns (Message) {126//         option (google.api.http) = {127//           patch: "/v1/messages/{message_id}"128//           body: "message"129//         };130//       }131//     }132//     message UpdateMessageRequest {133//       string message_id = 1; // mapped to the URL134//       Message message = 2;   // mapped to the body135//     }136//137// The following HTTP JSON to RPC mapping is enabled, where the138// representation of the JSON in the request body is determined by139// protos JSON encoding:140//141// - HTTP: `PATCH /v1/messages/123456 { "text": "Hi!" }`142// - gRPC: `UpdateMessage(message_id: "123456" message { text: "Hi!" })`143//144// The special name `*` can be used in the body mapping to define that145// every field not bound by the path template should be mapped to the146// request body.  This enables the following alternative definition of147// the update method:148//149//     service Messaging {150//       rpc UpdateMessage(Message) returns (Message) {151//         option (google.api.http) = {152//           patch: "/v1/messages/{message_id}"153//           body: "*"154//         };155//       }156//     }157//     message Message {158//       string message_id = 1;159//       string text = 2;160//     }161//162//163// The following HTTP JSON to RPC mapping is enabled:164//165// - HTTP: `PATCH /v1/messages/123456 { "text": "Hi!" }`166// - gRPC: `UpdateMessage(message_id: "123456" text: "Hi!")`167//168// Note that when using `*` in the body mapping, it is not possible to169// have HTTP parameters, as all fields not bound by the path end in170// the body. This makes this option more rarely used in practice when171// defining REST APIs. The common usage of `*` is in custom methods172// which don't use the URL at all for transferring data.173//174// It is possible to define multiple HTTP methods for one RPC by using175// the `additional_bindings` option. Example:176//177//     service Messaging {178//       rpc GetMessage(GetMessageRequest) returns (Message) {179//         option (google.api.http) = {180//           get: "/v1/messages/{message_id}"181//           additional_bindings {182//             get: "/v1/users/{user_id}/messages/{message_id}"183//           }184//         };185//       }186//     }187//     message GetMessageRequest {188//       string message_id = 1;189//       string user_id = 2;190//     }191//192// This enables the following two alternative HTTP JSON to RPC mappings:193//194// - HTTP: `GET /v1/messages/123456`195// - gRPC: `GetMessage(message_id: "123456")`196//197// - HTTP: `GET /v1/users/me/messages/123456`198// - gRPC: `GetMessage(user_id: "me" message_id: "123456")`199//200// Rules for HTTP mapping201//202// 1. Leaf request fields (recursive expansion nested messages in the request203//    message) are classified into three categories:204//    - Fields referred by the path template. They are passed via the URL path.205//    - Fields referred by the [HttpRule.body][google.api.HttpRule.body]. They206//    are passed via the HTTP207//      request body.208//    - All other fields are passed via the URL query parameters, and the209//      parameter name is the field path in the request message. A repeated210//      field can be represented as multiple query parameters under the same211//      name.212//  2. If [HttpRule.body][google.api.HttpRule.body] is "*", there is no URL213//  query parameter, all fields214//     are passed via URL path and HTTP request body.215//  3. If [HttpRule.body][google.api.HttpRule.body] is omitted, there is no HTTP216//  request body, all217//     fields are passed via URL path and URL query parameters.218//219// Path template syntax220//221//     Template = "/" Segments [ Verb ] ;222//     Segments = Segment { "/" Segment } ;223//     Segment  = "*" | "**" | LITERAL | Variable ;224//     Variable = "{" FieldPath [ "=" Segments ] "}" ;225//     FieldPath = IDENT { "." IDENT } ;226//     Verb     = ":" LITERAL ;227//228// The syntax `*` matches a single URL path segment. The syntax `**` matches229// zero or more URL path segments, which must be the last part of the URL path230// except the `Verb`.231//232// The syntax `Variable` matches part of the URL path as specified by its233// template. A variable template must not contain other variables. If a variable234// matches a single path segment, its template may be omitted, e.g. `{var}`235// is equivalent to `{var=*}`.236//237// The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`238// contains any reserved character, such characters should be percent-encoded239// before the matching.240//241// If a variable contains exactly one path segment, such as `"{var}"` or242// `"{var=*}"`, when such a variable is expanded into a URL path on the client243// side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The244// server side does the reverse decoding. Such variables show up in the245// [Discovery246// Document](https://developers.google.com/discovery/v1/reference/apis) as247// `{var}`.248//249// If a variable contains multiple path segments, such as `"{var=foo/*}"`250// or `"{var=**}"`, when such a variable is expanded into a URL path on the251// client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.252// The server side does the reverse decoding, except "%2F" and "%2f" are left253// unchanged. Such variables show up in the254// [Discovery255// Document](https://developers.google.com/discovery/v1/reference/apis) as256// `{+var}`.257//258// Using gRPC API Service Configuration259//260// gRPC API Service Configuration (service config) is a configuration language261// for configuring a gRPC service to become a user-facing product. The262// service config is simply the YAML representation of the `google.api.Service`263// proto message.264//265// As an alternative to annotating your proto file, you can configure gRPC266// transcoding in your service config YAML files. You do this by specifying a267// `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same268// effect as the proto annotation. This can be particularly useful if you269// have a proto that is reused in multiple services. Note that any transcoding270// specified in the service config will override any matching transcoding271// configuration in the proto.272//273// The following example selects a gRPC method and applies an `HttpRule` to it:274//275//     http:276//       rules:277//         - selector: example.v1.Messaging.GetMessage278//           get: /v1/messages/{message_id}/{sub.subfield}279//280// Special notes281//282// When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the283// proto to JSON conversion must follow the [proto3284// specification](https://developers.google.com/protocol-buffers/docs/proto3#json).285//286// While the single segment variable follows the semantics of287// [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String288// Expansion, the multi segment variable **does not** follow RFC 6570 Section289// 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion290// does not expand special characters like `?` and `#`, which would lead291// to invalid URLs. As the result, gRPC Transcoding uses a custom encoding292// for multi segment variables.293//294// The path variables **must not** refer to any repeated or mapped field,295// because client libraries are not capable of handling such variable expansion.296//297// The path variables **must not** capture the leading "/" character. The reason298// is that the most common use case "{var}" does not capture the leading "/"299// character. For consistency, all path variables must share the same behavior.300//301// Repeated message fields must not be mapped to URL query parameters, because302// no client library can support such complicated mapping.303//304// If an API needs to use a JSON array for request or response body, it can map305// the request or response body to a repeated field. However, some gRPC306// Transcoding implementations may not support this feature.307message HttpRule {308  // Selects a method to which this rule applies.309  //310  // Refer to [selector][google.api.DocumentationRule.selector] for syntax311  // details.312  string selector = 1;313 314  // Determines the URL pattern is matched by this rules. This pattern can be315  // used with any of the {get|put|post|delete|patch} methods. A custom method316  // can be defined using the 'custom' field.317  oneof pattern {318    // Maps to HTTP GET. Used for listing and getting information about319    // resources.320    string get = 2;321 322    // Maps to HTTP PUT. Used for replacing a resource.323    string put = 3;324 325    // Maps to HTTP POST. Used for creating a resource or performing an action.326    string post = 4;327 328    // Maps to HTTP DELETE. Used for deleting a resource.329    string delete = 5;330 331    // Maps to HTTP PATCH. Used for updating a resource.332    string patch = 6;333 334    // The custom pattern is used for specifying an HTTP method that is not335    // included in the `pattern` field, such as HEAD, or "*" to leave the336    // HTTP method unspecified for this rule. The wild-card rule is useful337    // for services that provide content to Web (HTML) clients.338    CustomHttpPattern custom = 8;339  }340 341  // The name of the request field whose value is mapped to the HTTP request342  // body, or `*` for mapping all request fields not captured by the path343  // pattern to the HTTP body, or omitted for not having any HTTP request body.344  //345  // NOTE: the referred field must be present at the top-level of the request346  // message type.347  string body = 7;348 349  // Optional. The name of the response field whose value is mapped to the HTTP350  // response body. When omitted, the entire response message will be used351  // as the HTTP response body.352  //353  // NOTE: The referred field must be present at the top-level of the response354  // message type.355  string response_body = 12;356 357  // Additional HTTP bindings for the selector. Nested bindings must358  // not contain an `additional_bindings` field themselves (that is,359  // the nesting may only be one level deep).360  repeated HttpRule additional_bindings = 11;361}362 363// A custom pattern is used for defining custom HTTP verb.364message CustomHttpPattern {365  // The name of this custom HTTP verb.366  string kind = 1;367 368  // The path matched by this custom verb.369  string path = 2;370}371