com.google.api.services.servicemanagement.model.HttpRule Maven / Gradle / Ivy
/*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
* in compliance with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License
* is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
* or implied. See the License for the specific language governing permissions and limitations under
* the License.
*/
/*
* This code was generated by https://github.com/googleapis/google-api-java-client-services/
* Modify at your own risk.
*/
package com.google.api.services.servicemanagement.model;
/**
* gRPC Transcoding gRPC Transcoding is a feature for mapping between a gRPC method and one or more
* HTTP REST endpoints. It allows developers to build a single API service that supports both gRPC
* APIs and REST APIs. Many systems, including [Google
* APIs](https://github.com/googleapis/googleapis), [Cloud
* Endpoints](https://cloud.google.com/endpoints), [gRPC Gateway](https://github.com/grpc-
* ecosystem/grpc-gateway), and [Envoy](https://github.com/envoyproxy/envoy) proxy support this
* feature and use it for large scale production services. `HttpRule` defines the schema of the
* gRPC/REST mapping. The mapping specifies how different portions of the gRPC request message are
* mapped to the URL path, URL query parameters, and HTTP request body. It also controls how the
* gRPC response message is mapped to the HTTP response body. `HttpRule` is typically specified as
* an `google.api.http` annotation on the gRPC method. Each mapping specifies a URL path template
* and an HTTP method. The path template may refer to one or more fields in the gRPC request
* message, as long as each field is a non-repeated field with a primitive (non-message) type. The
* path template controls how fields of the request message are mapped to the URL path. Example:
* service Messaging { rpc GetMessage(GetMessageRequest) returns (Message) { option
* (google.api.http) = { get: "/v1/{name=messages}" }; } } message GetMessageRequest { string name =
* 1; // Mapped to URL path. } message Message { string text = 1; // The resource content. } This
* enables an HTTP REST to gRPC mapping as below: - HTTP: `GET /v1/messages/123456` - gRPC:
* `GetMessage(name: "messages/123456")` Any fields in the request message which are not bound by
* the path template automatically become HTTP query parameters if there is no HTTP request body.
* For example: service Messaging { rpc GetMessage(GetMessageRequest) returns (Message) { option
* (google.api.http) = { get:"/v1/messages/{message_id}" }; } } message GetMessageRequest { message
* SubMessage { string subfield = 1; } string message_id = 1; // Mapped to URL path. int64 revision
* = 2; // Mapped to URL query parameter `revision`. SubMessage sub = 3; // Mapped to URL query
* parameter `sub.subfield`. } This enables a HTTP JSON to RPC mapping as below: - HTTP: `GET
* /v1/messages/123456?revision=2&sub.subfield=foo` - gRPC: `GetMessage(message_id: "123456"
* revision: 2 sub: SubMessage(subfield: "foo"))` Note that fields which are mapped to URL query
* parameters must have a primitive type or a repeated primitive type or a non-repeated message
* type. In the case of a repeated type, the parameter can be repeated in the URL as
* `...?param=A¶m=B`. In the case of a message type, each field of the message is mapped to a
* separate parameter, such as `...?foo.a=A&foo.b=B&foo.c=C`. For HTTP methods that allow a request
* body, the `body` field specifies the mapping. Consider a REST update method on the message
* resource collection: service Messaging { rpc UpdateMessage(UpdateMessageRequest) returns
* (Message) { option (google.api.http) = { patch: "/v1/messages/{message_id}" body: "message" }; }
* } message UpdateMessageRequest { string message_id = 1; // mapped to the URL Message message = 2;
* // mapped to the body } The following HTTP JSON to RPC mapping is enabled, where the
* representation of the JSON in the request body is determined by protos JSON encoding: - HTTP:
* `PATCH /v1/messages/123456 { "text": "Hi!" }` - gRPC: `UpdateMessage(message_id: "123456" message
* { text: "Hi!" })` The special name `*` can be used in the body mapping to define that every field
* not bound by the path template should be mapped to the request body. This enables the following
* alternative definition of the update method: service Messaging { rpc UpdateMessage(Message)
* returns (Message) { option (google.api.http) = { patch: "/v1/messages/{message_id}" body: "*" };
* } } message Message { string message_id = 1; string text = 2; } The following HTTP JSON to RPC
* mapping is enabled: - HTTP: `PATCH /v1/messages/123456 { "text": "Hi!" }` - gRPC:
* `UpdateMessage(message_id: "123456" text: "Hi!")` Note that when using `*` in the body mapping,
* it is not possible to have HTTP parameters, as all fields not bound by the path end in the body.
* This makes this option more rarely used in practice when defining REST APIs. The common usage of
* `*` is in custom methods which don't use the URL at all for transferring data. It is possible to
* define multiple HTTP methods for one RPC by using the `additional_bindings` option. Example:
* service Messaging { rpc GetMessage(GetMessageRequest) returns (Message) { option
* (google.api.http) = { get: "/v1/messages/{message_id}" additional_bindings { get:
* "/v1/users/{user_id}/messages/{message_id}" } }; } } message GetMessageRequest { string
* message_id = 1; string user_id = 2; } This enables the following two alternative HTTP JSON to RPC
* mappings: - HTTP: `GET /v1/messages/123456` - gRPC: `GetMessage(message_id: "123456")` - HTTP:
* `GET /v1/users/me/messages/123456` - gRPC: `GetMessage(user_id: "me" message_id: "123456")` Rules
* for HTTP mapping 1. Leaf request fields (recursive expansion nested messages in the request
* message) are classified into three categories: - Fields referred by the path template. They are
* passed via the URL path. - Fields referred by the HttpRule.body. They are passed via the HTTP
* request body. - All other fields are passed via the URL query parameters, and the parameter name
* is the field path in the request message. A repeated field can be represented as multiple query
* parameters under the same name. 2. If HttpRule.body is "*", there is no URL query parameter, all
* fields are passed via URL path and HTTP request body. 3. If HttpRule.body is omitted, there is no
* HTTP request body, all fields are passed via URL path and URL query parameters. Path template
* syntax Template = "/" Segments [ Verb ] ; Segments = Segment { "/" Segment } ; Segment = "*" |
* "**" | LITERAL | Variable ; Variable = "{" FieldPath [ "=" Segments ] "}" ; FieldPath = IDENT {
* "." IDENT } ; Verb = ":" LITERAL ; The syntax `*` matches a single URL path segment. The syntax
* `**` matches zero or more URL path segments, which must be the last part of the URL path except
* the `Verb`. The syntax `Variable` matches part of the URL path as specified by its template. A
* variable template must not contain other variables. If a variable matches a single path segment,
* its template may be omitted, e.g. `{var}` is equivalent to `{var=*}`. The syntax `LITERAL`
* matches literal text in the URL path. If the `LITERAL` contains any reserved character, such
* characters should be percent-encoded before the matching. If a variable contains exactly one path
* segment, such as `"{var}"` or `"{var=*}"`, when such a variable is expanded into a URL path on
* the client side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The server side
* does the reverse decoding. Such variables show up in the [Discovery
* Document](https://developers.google.com/discovery/v1/reference/apis) as `{var}`. If a variable
* contains multiple path segments, such as `"{var=foo}"` or `"{var=**}"`, when such a variable is
* expanded into a URL path on the client side, all characters except `[-_.~/0-9a-zA-Z]` are
* percent-encoded. The server side does the reverse decoding, except "%2F" and "%2f" are left
* unchanged. Such variables show up in the [Discovery
* Document](https://developers.google.com/discovery/v1/reference/apis) as `{+var}`. Using gRPC API
* Service Configuration gRPC API Service Configuration (service config) is a configuration language
* for configuring a gRPC service to become a user-facing product. The service config is simply the
* YAML representation of the `google.api.Service` proto message. As an alternative to annotating
* your proto file, you can configure gRPC transcoding in your service config YAML files. You do
* this by specifying a `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same
* effect as the proto annotation. This can be particularly useful if you have a proto that is
* reused in multiple services. Note that any transcoding specified in the service config will
* override any matching transcoding configuration in the proto. The following example selects a
* gRPC method and applies an `HttpRule` to it: http: rules: - selector:
* example.v1.Messaging.GetMessage get: /v1/messages/{message_id}/{sub.subfield} Special notes When
* gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the proto to JSON conversion must
* follow the [proto3 specification](https://developers.google.com/protocol-
* buffers/docs/proto3#json). While the single segment variable follows the semantics of [RFC
* 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String Expansion, the multi
* segment variable **does not** follow RFC 6570 Section 3.2.3 Reserved Expansion. The reason is
* that the Reserved Expansion does not expand special characters like `?` and `#`, which would lead
* to invalid URLs. As the result, gRPC Transcoding uses a custom encoding for multi segment
* variables. The path variables **must not** refer to any repeated or mapped field, because client
* libraries are not capable of handling such variable expansion. The path variables **must not**
* capture the leading "/" character. The reason is that the most common use case "{var}" does not
* capture the leading "/" character. For consistency, all path variables must share the same
* behavior. Repeated message fields must not be mapped to URL query parameters, because no client
* library can support such complicated mapping. If an API needs to use a JSON array for request or
* response body, it can map the request or response body to a repeated field. However, some gRPC
* Transcoding implementations may not support this feature.
*
* This is the Java data model class that specifies how to parse/serialize into the JSON that is
* transmitted over HTTP when working with the Service Management API. For a detailed explanation
* see:
* https://developers.google.com/api-client-library/java/google-http-java-client/json
*
*
* @author Google, Inc.
*/
@SuppressWarnings("javadoc")
public final class HttpRule extends com.google.api.client.json.GenericJson {
/**
* Additional HTTP bindings for the selector. Nested bindings must not contain an
* `additional_bindings` field themselves (that is, the nesting may only be one level deep).
* The value may be {@code null}.
*/
@com.google.api.client.util.Key
private java.util.List additionalBindings;
/**
* The name of the request field whose value is mapped to the HTTP request body, or `*` for
* mapping all request fields not captured by the path pattern to the HTTP body, or omitted for
* not having any HTTP request body. NOTE: the referred field must be present at the top-level of
* the request message type.
* The value may be {@code null}.
*/
@com.google.api.client.util.Key
private java.lang.String body;
/**
* The custom pattern is used for specifying an HTTP method that is not included in the `pattern`
* field, such as HEAD, or "*" to leave the HTTP method unspecified for this rule. The wild-card
* rule is useful for services that provide content to Web (HTML) clients.
* The value may be {@code null}.
*/
@com.google.api.client.util.Key
private CustomHttpPattern custom;
/**
* Maps to HTTP DELETE. Used for deleting a resource.
* The value may be {@code null}.
*/
@com.google.api.client.util.Key
private java.lang.String delete;
/**
* Maps to HTTP GET. Used for listing and getting information about resources.
* The value may be {@code null}.
*/
@com.google.api.client.util.Key
private java.lang.String get;
/**
* Maps to HTTP PATCH. Used for updating a resource.
* The value may be {@code null}.
*/
@com.google.api.client.util.Key
private java.lang.String patch;
/**
* Maps to HTTP POST. Used for creating a resource or performing an action.
* The value may be {@code null}.
*/
@com.google.api.client.util.Key
private java.lang.String post;
/**
* Maps to HTTP PUT. Used for replacing a resource.
* The value may be {@code null}.
*/
@com.google.api.client.util.Key
private java.lang.String put;
/**
* Optional. The name of the response field whose value is mapped to the HTTP response body. When
* omitted, the entire response message will be used as the HTTP response body. NOTE: The referred
* field must be present at the top-level of the response message type.
* The value may be {@code null}.
*/
@com.google.api.client.util.Key
private java.lang.String responseBody;
/**
* Selects a method to which this rule applies. Refer to selector for syntax details.
* The value may be {@code null}.
*/
@com.google.api.client.util.Key
private java.lang.String selector;
/**
* Additional HTTP bindings for the selector. Nested bindings must not contain an
* `additional_bindings` field themselves (that is, the nesting may only be one level deep).
* @return value or {@code null} for none
*/
public java.util.List getAdditionalBindings() {
return additionalBindings;
}
/**
* Additional HTTP bindings for the selector. Nested bindings must not contain an
* `additional_bindings` field themselves (that is, the nesting may only be one level deep).
* @param additionalBindings additionalBindings or {@code null} for none
*/
public HttpRule setAdditionalBindings(java.util.List additionalBindings) {
this.additionalBindings = additionalBindings;
return this;
}
/**
* The name of the request field whose value is mapped to the HTTP request body, or `*` for
* mapping all request fields not captured by the path pattern to the HTTP body, or omitted for
* not having any HTTP request body. NOTE: the referred field must be present at the top-level of
* the request message type.
* @return value or {@code null} for none
*/
public java.lang.String getBody() {
return body;
}
/**
* The name of the request field whose value is mapped to the HTTP request body, or `*` for
* mapping all request fields not captured by the path pattern to the HTTP body, or omitted for
* not having any HTTP request body. NOTE: the referred field must be present at the top-level of
* the request message type.
* @param body body or {@code null} for none
*/
public HttpRule setBody(java.lang.String body) {
this.body = body;
return this;
}
/**
* The custom pattern is used for specifying an HTTP method that is not included in the `pattern`
* field, such as HEAD, or "*" to leave the HTTP method unspecified for this rule. The wild-card
* rule is useful for services that provide content to Web (HTML) clients.
* @return value or {@code null} for none
*/
public CustomHttpPattern getCustom() {
return custom;
}
/**
* The custom pattern is used for specifying an HTTP method that is not included in the `pattern`
* field, such as HEAD, or "*" to leave the HTTP method unspecified for this rule. The wild-card
* rule is useful for services that provide content to Web (HTML) clients.
* @param custom custom or {@code null} for none
*/
public HttpRule setCustom(CustomHttpPattern custom) {
this.custom = custom;
return this;
}
/**
* Maps to HTTP DELETE. Used for deleting a resource.
* @return value or {@code null} for none
*/
public java.lang.String getDelete() {
return delete;
}
/**
* Maps to HTTP DELETE. Used for deleting a resource.
* @param delete delete or {@code null} for none
*/
public HttpRule setDelete(java.lang.String delete) {
this.delete = delete;
return this;
}
/**
* Maps to HTTP GET. Used for listing and getting information about resources.
* @return value or {@code null} for none
*/
public java.lang.String getGet() {
return get;
}
/**
* Maps to HTTP GET. Used for listing and getting information about resources.
* @param get get or {@code null} for none
*/
public HttpRule setGet(java.lang.String get) {
this.get = get;
return this;
}
/**
* Maps to HTTP PATCH. Used for updating a resource.
* @return value or {@code null} for none
*/
public java.lang.String getPatch() {
return patch;
}
/**
* Maps to HTTP PATCH. Used for updating a resource.
* @param patch patch or {@code null} for none
*/
public HttpRule setPatch(java.lang.String patch) {
this.patch = patch;
return this;
}
/**
* Maps to HTTP POST. Used for creating a resource or performing an action.
* @return value or {@code null} for none
*/
public java.lang.String getPost() {
return post;
}
/**
* Maps to HTTP POST. Used for creating a resource or performing an action.
* @param post post or {@code null} for none
*/
public HttpRule setPost(java.lang.String post) {
this.post = post;
return this;
}
/**
* Maps to HTTP PUT. Used for replacing a resource.
* @return value or {@code null} for none
*/
public java.lang.String getPut() {
return put;
}
/**
* Maps to HTTP PUT. Used for replacing a resource.
* @param put put or {@code null} for none
*/
public HttpRule setPut(java.lang.String put) {
this.put = put;
return this;
}
/**
* Optional. The name of the response field whose value is mapped to the HTTP response body. When
* omitted, the entire response message will be used as the HTTP response body. NOTE: The referred
* field must be present at the top-level of the response message type.
* @return value or {@code null} for none
*/
public java.lang.String getResponseBody() {
return responseBody;
}
/**
* Optional. The name of the response field whose value is mapped to the HTTP response body. When
* omitted, the entire response message will be used as the HTTP response body. NOTE: The referred
* field must be present at the top-level of the response message type.
* @param responseBody responseBody or {@code null} for none
*/
public HttpRule setResponseBody(java.lang.String responseBody) {
this.responseBody = responseBody;
return this;
}
/**
* Selects a method to which this rule applies. Refer to selector for syntax details.
* @return value or {@code null} for none
*/
public java.lang.String getSelector() {
return selector;
}
/**
* Selects a method to which this rule applies. Refer to selector for syntax details.
* @param selector selector or {@code null} for none
*/
public HttpRule setSelector(java.lang.String selector) {
this.selector = selector;
return this;
}
@Override
public HttpRule set(String fieldName, Object value) {
return (HttpRule) super.set(fieldName, value);
}
@Override
public HttpRule clone() {
return (HttpRule) super.clone();
}
}