You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
201 lines
6.5 KiB
201 lines
6.5 KiB
// Copyright (c) 2015, Google Inc. |
|
// |
|
// 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. |
|
|
|
syntax = "proto3"; |
|
|
|
package google.api; |
|
|
|
option java_multiple_files = true; |
|
option java_outer_classname = "HttpProto"; |
|
option java_package = "com.google.api"; |
|
|
|
|
|
// `HttpRule` defines the mapping of an RPC method to one or more HTTP REST API |
|
// methods. The mapping determines what portions of the request message are |
|
// populated from the path, query parameters, or body of the HTTP request. The |
|
// mapping is typically specified as an `google.api.http` annotation, see |
|
// "google/api/annotations.proto" for details. |
|
// |
|
// The mapping consists of a required field specifying a path template and an |
|
// optional `body` field specifying what data is represented in the HTTP request |
|
// body. The field name for the path indicates the HTTP method. Here is an |
|
// example of a REST API defined using this feature. |
|
// |
|
// ``` |
|
// package example.messaging.v1; |
|
// |
|
// import "google/api/annotations.proto"; |
|
// import "google/protobuf/empty.proto"; |
|
// |
|
// service Messaging { |
|
// // Standard List method. |
|
// rpc ListMessages(ListMessagesRequest) returns (ListMessagesResponse) { |
|
// option (google.api.http).get = "/v1/messages"; |
|
// // No body for HTTP GET. |
|
// } |
|
// |
|
// // Standard Create method. |
|
// rpc CreateMessage(CreateMessageRequest) returns (Message) { |
|
// option (google.api.http) = { |
|
// post: "/v1/messages" |
|
// body: "message" |
|
// }; |
|
// } |
|
// |
|
// // Standard Get method. |
|
// rpc GetMessage(GetMessageRequest) returns (Message) { |
|
// option (google.api.http).get = "/v1/messages/{message_id}"; |
|
// // No body for HTTP GET. |
|
// } |
|
// |
|
// // Standard Update method. |
|
// rpc UpdateMessage(UpdateMessageRequest) returns (Message) { |
|
// option (google.api.http) = { |
|
// put: "/v1/messages/{message_id}" |
|
// body: "message" |
|
// }; |
|
// } |
|
// // Standard Delete method. |
|
// rpc DeleteMessage(DeleteMessageRequest) returns (google.protobuf.Empty) { |
|
// option (google.api.http).delete = "/v1/messages/{message_id}"; |
|
// // No body for HTTP DELETE. |
|
// } |
|
// |
|
// // A custom Forward method. |
|
// rpc ForwardMessage(ForwardMessageRequest) |
|
// returns (ForwardMessageResponse) { |
|
// option (google.api.http) { |
|
// post: "/v1/messages/{message_id}:forward" |
|
// body: "*" |
|
// }; |
|
// } |
|
// } |
|
// |
|
// message Message { |
|
// string text = 1; |
|
// } |
|
// |
|
// message ListMessageRequest { |
|
// } |
|
// |
|
// message ListMesageResponse { |
|
// repeated Message messages = 1; |
|
// } |
|
// |
|
// message CreateMessageRequest { |
|
// Message message = 1; |
|
// } |
|
// |
|
// message GetMessageRequest { |
|
// string message_id = 1; |
|
// } |
|
// |
|
// message UpdateMessageRequest { |
|
// string message_id = 1; |
|
// Message message = 2; |
|
// } |
|
// |
|
// message DeleteMessageRequest { |
|
// string message_id = 1; |
|
// } |
|
// |
|
// message ForwardMessageRequest { |
|
// string message_id = 1; |
|
// string forward_address = 2; |
|
// } |
|
// |
|
// message ForwardMessageResponse { |
|
// } |
|
// ``` |
|
// |
|
// NOTE: the notation `{message_id}` binds to the field `message_id` in the |
|
// corresponding method's request message. |
|
// |
|
// The rules for mapping HTTP path, query parameters, and body fields |
|
// to the request message are as follows: |
|
// |
|
// 1. The `body` field specifies either `*` or a field path, or is |
|
// omitted. If omitted, it assumes there is no HTTP body. |
|
// 2. Leaf fields (recursive expansion of nested messages in the |
|
// request) can be classified into three types: |
|
// (a) Matched in the URL template. |
|
// (b) Covered by body (if body is `*`, everything except (a) fields; |
|
// else everything under the body field) |
|
// (c) All other fields. |
|
// 3. URL query parameters found in the HTTP request are mapped to (c) fields. |
|
// 4. Any body sent with an HTTP request can contain only (b) fields. |
|
// |
|
// The syntax of the path template is as follows: |
|
// |
|
// Template = "/" Segments [ Verb ] ; |
|
// Segments = Segment { "/" Segment } ; |
|
// Segment = "*" | "**" | LITERAL | Variable ; |
|
// Variable = "{" FieldPath [ "=" Segments ] "}" ; |
|
// FieldPath = IDENT { "." IDENT } ; |
|
// Verb = ":" LITERAL ; |
|
// |
|
// `*` matches a single path component, `**` zero or more path components, and |
|
// `LITERAL` a constant. A `Variable` can match an entire path as specified |
|
// again by a template; this nested template must not contain further variables. |
|
// If no template is given with a variable, it matches a single path component. |
|
// The notation `{var}` is henceforth equivalent to `{var=*}`. NOTE: the field |
|
// paths in variables and in the `body` must not refer to repeated fields. |
|
// |
|
// Use CustomHttpPattern to specify any HTTP method that is not included in the |
|
// pattern field, such as HEAD, or "*" to leave the HTTP method unspecified for |
|
// a given URL path rule. The wild-card rule is useful for services that provide |
|
// content to Web (HTML) clients. |
|
message HttpRule { |
|
|
|
// Determines the URL pattern is matched by this rules. This pattern can be |
|
// used with any of the {get|put|post|delete|patch} methods. A custom method |
|
// can be defined using the 'custom' field. |
|
oneof pattern { |
|
// Used for listing and getting information about resources. |
|
string get = 2; |
|
|
|
// Used for updating a resource. |
|
string put = 3; |
|
|
|
// Used for creating a resource. |
|
string post = 4; |
|
|
|
// Used for deleting a resource. |
|
string delete = 5; |
|
|
|
// Used for updating a resource. |
|
string patch = 6; |
|
|
|
// Custom pattern is used for defining custom verbs. |
|
CustomHttpPattern custom = 8; |
|
} |
|
|
|
// The name of the request field whose value is mapped to the HTTP body, or |
|
// `*` for mapping all fields not captured by the path pattern to the HTTP |
|
// body. NOTE: the referred field must not be a repeated field. |
|
string body = 7; |
|
|
|
// Additional HTTP bindings for the selector. Nested bindings must not |
|
// specify a selector and must not contain additional bindings. |
|
repeated HttpRule additional_bindings = 11; |
|
} |
|
|
|
// A custom pattern is used for defining custom HTTP verb. |
|
message CustomHttpPattern { |
|
// The name of this custom HTTP verb. |
|
string kind = 1; |
|
|
|
// The path matched by this custom verb. |
|
string path = 2; |
|
}
|
|
|