com.google.api.services.serviceconsumermanagement.v1.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.serviceconsumermanagement.v1.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 | gRPC -----|----- `GET /v1/messages/123456` | `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 | gRPC -----|----- `GET
* /v1/messages/123456?revision=2=foo` | `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=B`. In the case of a
* message type, each field of the message is mapped to a separate parameter, such as
* `...?foo.a=A=B=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 | gRPC -----|----- `PATCH /v1/messages/123456 { "text":
* "Hi!" }` | `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
* | gRPC -----|----- `PATCH /v1/messages/123456 { "text": "Hi!" }` | `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 | gRPC -----|----- `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`
* `GET /v1/users/me/messages/123456` | `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. Example: http: rules: # Selects a
* gRPC method and applies HttpRule to it. - 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 Consumer 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();
}
}