nominal_api/proto/google.api.rs
1// This file is @generated by prost-build.
2/// Defines the HTTP configuration for an API service. It contains a list of
3/// [HttpRule][google.api.HttpRule], each specifying the mapping of an RPC method
4/// to one or more HTTP REST API methods.
5#[derive(Clone, PartialEq, ::prost::Message)]
6pub struct Http {
7 /// A list of HTTP configuration rules that apply to individual API methods.
8 ///
9 /// **NOTE:** All service configuration rules follow "last one wins" order.
10 #[prost(message, repeated, tag = "1")]
11 pub rules: ::prost::alloc::vec::Vec<HttpRule>,
12 /// When set to true, URL path parameters will be fully URI-decoded except in
13 /// cases of single segment matches in reserved expansion, where "%2F" will be
14 /// left encoded.
15 ///
16 /// The default behavior is to not decode RFC 6570 reserved characters in multi
17 /// segment matches.
18 #[prost(bool, tag = "2")]
19 pub fully_decode_reserved_expansion: bool,
20}
21/// gRPC Transcoding
22///
23/// gRPC Transcoding is a feature for mapping between a gRPC method and one or
24/// more HTTP REST endpoints. It allows developers to build a single API service
25/// that supports both gRPC APIs and REST APIs. Many systems, including [Google
26/// APIs](<https://github.com/googleapis/googleapis>),
27/// [Cloud Endpoints](<https://cloud.google.com/endpoints>), [gRPC
28/// Gateway](<https://github.com/grpc-ecosystem/grpc-gateway>),
29/// and [Envoy](<https://github.com/envoyproxy/envoy>) proxy support this feature
30/// and use it for large scale production services.
31///
32/// `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies
33/// how different portions of the gRPC request message are mapped to the URL
34/// path, URL query parameters, and HTTP request body. It also controls how the
35/// gRPC response message is mapped to the HTTP response body. `HttpRule` is
36/// typically specified as an `google.api.http` annotation on the gRPC method.
37///
38/// Each mapping specifies a URL path template and an HTTP method. The path
39/// template may refer to one or more fields in the gRPC request message, as long
40/// as each field is a non-repeated field with a primitive (non-message) type.
41/// The path template controls how fields of the request message are mapped to
42/// the URL path.
43///
44/// Example:
45///
46/// service Messaging {
47/// rpc GetMessage(GetMessageRequest) returns (Message) {
48/// option (google.api.http) = {
49/// get: "/v1/{name=messages/*}"
50/// };
51/// }
52/// }
53/// message GetMessageRequest {
54/// string name = 1; // Mapped to URL path.
55/// }
56/// message Message {
57/// string text = 1; // The resource content.
58/// }
59///
60/// This enables an HTTP REST to gRPC mapping as below:
61///
62/// - HTTP: `GET /v1/messages/123456`
63/// - gRPC: `GetMessage(name: "messages/123456")`
64///
65/// Any fields in the request message which are not bound by the path template
66/// automatically become HTTP query parameters if there is no HTTP request body.
67/// For example:
68///
69/// service Messaging {
70/// rpc GetMessage(GetMessageRequest) returns (Message) {
71/// option (google.api.http) = {
72/// get:"/v1/messages/{message_id}"
73/// };
74/// }
75/// }
76/// message GetMessageRequest {
77/// message SubMessage {
78/// string subfield = 1;
79/// }
80/// string message_id = 1; // Mapped to URL path.
81/// int64 revision = 2; // Mapped to URL query parameter `revision`.
82/// SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.
83/// }
84///
85/// This enables a HTTP JSON to RPC mapping as below:
86///
87/// - HTTP: `GET /v1/messages/123456?revision=2&sub.subfield=foo`
88/// - gRPC: `GetMessage(message_id: "123456" revision: 2 sub:
89/// SubMessage(subfield: "foo"))`
90///
91/// Note that fields which are mapped to URL query parameters must have a
92/// primitive type or a repeated primitive type or a non-repeated message type.
93/// In the case of a repeated type, the parameter can be repeated in the URL
94/// as `...?param=A¶m=B`. In the case of a message type, each field of the
95/// message is mapped to a separate parameter, such as
96/// `...?foo.a=A&foo.b=B&foo.c=C`.
97///
98/// For HTTP methods that allow a request body, the `body` field
99/// specifies the mapping. Consider a REST update method on the
100/// message resource collection:
101///
102/// service Messaging {
103/// rpc UpdateMessage(UpdateMessageRequest) returns (Message) {
104/// option (google.api.http) = {
105/// patch: "/v1/messages/{message_id}"
106/// body: "message"
107/// };
108/// }
109/// }
110/// message UpdateMessageRequest {
111/// string message_id = 1; // mapped to the URL
112/// Message message = 2; // mapped to the body
113/// }
114///
115/// The following HTTP JSON to RPC mapping is enabled, where the
116/// representation of the JSON in the request body is determined by
117/// protos JSON encoding:
118///
119/// - HTTP: `PATCH /v1/messages/123456 { "text": "Hi!" }`
120/// - gRPC: `UpdateMessage(message_id: "123456" message { text: "Hi!" })`
121///
122/// The special name `*` can be used in the body mapping to define that
123/// every field not bound by the path template should be mapped to the
124/// request body. This enables the following alternative definition of
125/// the update method:
126///
127/// service Messaging {
128/// rpc UpdateMessage(Message) returns (Message) {
129/// option (google.api.http) = {
130/// patch: "/v1/messages/{message_id}"
131/// body: "*"
132/// };
133/// }
134/// }
135/// message Message {
136/// string message_id = 1;
137/// string text = 2;
138/// }
139///
140///
141/// The following HTTP JSON to RPC mapping is enabled:
142///
143/// - HTTP: `PATCH /v1/messages/123456 { "text": "Hi!" }`
144/// - gRPC: `UpdateMessage(message_id: "123456" text: "Hi!")`
145///
146/// Note that when using `*` in the body mapping, it is not possible to
147/// have HTTP parameters, as all fields not bound by the path end in
148/// the body. This makes this option more rarely used in practice when
149/// defining REST APIs. The common usage of `*` is in custom methods
150/// which don't use the URL at all for transferring data.
151///
152/// It is possible to define multiple HTTP methods for one RPC by using
153/// the `additional_bindings` option. Example:
154///
155/// service Messaging {
156/// rpc GetMessage(GetMessageRequest) returns (Message) {
157/// option (google.api.http) = {
158/// get: "/v1/messages/{message_id}"
159/// additional_bindings {
160/// get: "/v1/users/{user_id}/messages/{message_id}"
161/// }
162/// };
163/// }
164/// }
165/// message GetMessageRequest {
166/// string message_id = 1;
167/// string user_id = 2;
168/// }
169///
170/// This enables the following two alternative HTTP JSON to RPC mappings:
171///
172/// - HTTP: `GET /v1/messages/123456`
173/// - gRPC: `GetMessage(message_id: "123456")`
174///
175/// - HTTP: `GET /v1/users/me/messages/123456`
176/// - gRPC: `GetMessage(user_id: "me" message_id: "123456")`
177///
178/// Rules for HTTP mapping
179///
180/// 1. Leaf request fields (recursive expansion nested messages in the request
181/// message) are classified into three categories:
182/// - Fields referred by the path template. They are passed via the URL path.
183/// - Fields referred by the [HttpRule.body][google.api.HttpRule.body]. They
184/// are passed via the HTTP
185/// request body.
186/// - All other fields are passed via the URL query parameters, and the
187/// parameter name is the field path in the request message. A repeated
188/// field can be represented as multiple query parameters under the same
189/// name.
190/// 2. If [HttpRule.body][google.api.HttpRule.body] is "*", there is no URL
191/// query parameter, all fields
192/// are passed via URL path and HTTP request body.
193/// 3. If [HttpRule.body][google.api.HttpRule.body] is omitted, there is no HTTP
194/// request body, all
195/// fields are passed via URL path and URL query parameters.
196///
197/// Path template syntax
198///
199/// Template = "/" Segments \[ Verb \] ;
200/// Segments = Segment { "/" Segment } ;
201/// Segment = "*" | "**" | LITERAL | Variable ;
202/// Variable = "{" FieldPath \[ "=" Segments \] "}" ;
203/// FieldPath = IDENT { "." IDENT } ;
204/// Verb = ":" LITERAL ;
205///
206/// The syntax `*` matches a single URL path segment. The syntax `**` matches
207/// zero or more URL path segments, which must be the last part of the URL path
208/// except the `Verb`.
209///
210/// The syntax `Variable` matches part of the URL path as specified by its
211/// template. A variable template must not contain other variables. If a variable
212/// matches a single path segment, its template may be omitted, e.g. `{var}`
213/// is equivalent to `{var=*}`.
214///
215/// The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`
216/// contains any reserved character, such characters should be percent-encoded
217/// before the matching.
218///
219/// If a variable contains exactly one path segment, such as `"{var}"` or
220/// `"{var=*}"`, when such a variable is expanded into a URL path on the client
221/// side, all characters except `\[-_.~0-9a-zA-Z\]` are percent-encoded. The
222/// server side does the reverse decoding. Such variables show up in the
223/// [Discovery
224/// Document](<https://developers.google.com/discovery/v1/reference/apis>) as
225/// `{var}`.
226///
227/// If a variable contains multiple path segments, such as `"{var=foo/*}"`
228/// or `"{var=**}"`, when such a variable is expanded into a URL path on the
229/// client side, all characters except `\[-_.~/0-9a-zA-Z\]` are percent-encoded.
230/// The server side does the reverse decoding, except "%2F" and "%2f" are left
231/// unchanged. Such variables show up in the
232/// [Discovery
233/// Document](<https://developers.google.com/discovery/v1/reference/apis>) as
234/// `{+var}`.
235///
236/// Using gRPC API Service Configuration
237///
238/// gRPC API Service Configuration (service config) is a configuration language
239/// for configuring a gRPC service to become a user-facing product. The
240/// service config is simply the YAML representation of the `google.api.Service`
241/// proto message.
242///
243/// As an alternative to annotating your proto file, you can configure gRPC
244/// transcoding in your service config YAML files. You do this by specifying a
245/// `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same
246/// effect as the proto annotation. This can be particularly useful if you
247/// have a proto that is reused in multiple services. Note that any transcoding
248/// specified in the service config will override any matching transcoding
249/// configuration in the proto.
250///
251/// The following example selects a gRPC method and applies an `HttpRule` to it:
252///
253/// http:
254/// rules:
255/// - selector: example.v1.Messaging.GetMessage
256/// get: /v1/messages/{message_id}/{sub.subfield}
257///
258/// Special notes
259///
260/// When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the
261/// proto to JSON conversion must follow the [proto3
262/// specification](<https://developers.google.com/protocol-buffers/docs/proto3#json>).
263///
264/// While the single segment variable follows the semantics of
265/// [RFC 6570](<https://tools.ietf.org/html/rfc6570>) Section 3.2.2 Simple String
266/// Expansion, the multi segment variable **does not** follow RFC 6570 Section
267/// 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion
268/// does not expand special characters like `?` and `#`, which would lead
269/// to invalid URLs. As the result, gRPC Transcoding uses a custom encoding
270/// for multi segment variables.
271///
272/// The path variables **must not** refer to any repeated or mapped field,
273/// because client libraries are not capable of handling such variable expansion.
274///
275/// The path variables **must not** capture the leading "/" character. The reason
276/// is that the most common use case "{var}" does not capture the leading "/"
277/// character. For consistency, all path variables must share the same behavior.
278///
279/// Repeated message fields must not be mapped to URL query parameters, because
280/// no client library can support such complicated mapping.
281///
282/// If an API needs to use a JSON array for request or response body, it can map
283/// the request or response body to a repeated field. However, some gRPC
284/// Transcoding implementations may not support this feature.
285#[derive(Clone, PartialEq, ::prost::Message)]
286pub struct HttpRule {
287 /// Selects a method to which this rule applies.
288 ///
289 /// Refer to [selector][google.api.DocumentationRule.selector] for syntax
290 /// details.
291 #[prost(string, tag = "1")]
292 pub selector: ::prost::alloc::string::String,
293 /// The name of the request field whose value is mapped to the HTTP request
294 /// body, or `*` for mapping all request fields not captured by the path
295 /// pattern to the HTTP body, or omitted for not having any HTTP request body.
296 ///
297 /// NOTE: the referred field must be present at the top-level of the request
298 /// message type.
299 #[prost(string, tag = "7")]
300 pub body: ::prost::alloc::string::String,
301 /// Optional. The name of the response field whose value is mapped to the HTTP
302 /// response body. When omitted, the entire response message will be used
303 /// as the HTTP response body.
304 ///
305 /// NOTE: The referred field must be present at the top-level of the response
306 /// message type.
307 #[prost(string, tag = "12")]
308 pub response_body: ::prost::alloc::string::String,
309 /// Additional HTTP bindings for the selector. Nested bindings must
310 /// not contain an `additional_bindings` field themselves (that is,
311 /// the nesting may only be one level deep).
312 #[prost(message, repeated, tag = "11")]
313 pub additional_bindings: ::prost::alloc::vec::Vec<HttpRule>,
314 /// Determines the URL pattern is matched by this rules. This pattern can be
315 /// used with any of the {get|put|post|delete|patch} methods. A custom method
316 /// can be defined using the 'custom' field.
317 #[prost(oneof = "http_rule::Pattern", tags = "2, 3, 4, 5, 6, 8")]
318 pub pattern: ::core::option::Option<http_rule::Pattern>,
319}
320/// Nested message and enum types in `HttpRule`.
321pub mod http_rule {
322 /// Determines the URL pattern is matched by this rules. This pattern can be
323 /// used with any of the {get|put|post|delete|patch} methods. A custom method
324 /// can be defined using the 'custom' field.
325 #[derive(Clone, PartialEq, ::prost::Oneof)]
326 pub enum Pattern {
327 /// Maps to HTTP GET. Used for listing and getting information about
328 /// resources.
329 #[prost(string, tag = "2")]
330 Get(::prost::alloc::string::String),
331 /// Maps to HTTP PUT. Used for replacing a resource.
332 #[prost(string, tag = "3")]
333 Put(::prost::alloc::string::String),
334 /// Maps to HTTP POST. Used for creating a resource or performing an action.
335 #[prost(string, tag = "4")]
336 Post(::prost::alloc::string::String),
337 /// Maps to HTTP DELETE. Used for deleting a resource.
338 #[prost(string, tag = "5")]
339 Delete(::prost::alloc::string::String),
340 /// Maps to HTTP PATCH. Used for updating a resource.
341 #[prost(string, tag = "6")]
342 Patch(::prost::alloc::string::String),
343 /// The custom pattern is used for specifying an HTTP method that is not
344 /// included in the `pattern` field, such as HEAD, or "*" to leave the
345 /// HTTP method unspecified for this rule. The wild-card rule is useful
346 /// for services that provide content to Web (HTML) clients.
347 #[prost(message, tag = "8")]
348 Custom(super::CustomHttpPattern),
349 }
350}
351/// A custom pattern is used for defining custom HTTP verb.
352#[derive(Clone, PartialEq, ::prost::Message)]
353pub struct CustomHttpPattern {
354 /// The name of this custom HTTP verb.
355 #[prost(string, tag = "1")]
356 pub kind: ::prost::alloc::string::String,
357 /// The path matched by this custom verb.
358 #[prost(string, tag = "2")]
359 pub path: ::prost::alloc::string::String,
360}