Update documentation on http annotation.
This commit is contained in:
wora
parent
3ee9064570
commit
fc7061a35c
|
|
@ -21,107 +21,150 @@ 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.
|
||||
// `HttpRule` defines the mapping of an RPC method to one or more HTTP
|
||||
// REST APIs. 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";
|
||||
// The mapping consists of a field specifying the path template and
|
||||
// method kind. The path template can refer to fields in the request
|
||||
// message, as in the example below which describes a REST GET
|
||||
// operation on a resource collection of messages:
|
||||
//
|
||||
// ```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.
|
||||
// }
|
||||
// }
|
||||
// message GetMessageRequest {
|
||||
// string message_id = 1; // mapped to the URL
|
||||
// }
|
||||
// message Message {
|
||||
// string text = 1; // content of the resource
|
||||
// }
|
||||
// ```
|
||||
//
|
||||
// // Standard Update method.
|
||||
// This definition enables an automatic, bidrectional mapping of HTTP
|
||||
// JSON to RPC. Example:
|
||||
//
|
||||
// HTTP | RPC
|
||||
// -----|-----
|
||||
// `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`
|
||||
//
|
||||
// In general, not only fields but also field paths can be referenced
|
||||
// from a path pattern. Fields mapped to the path pattern cannot be
|
||||
// repeated and must have a primitive (non-message) type.
|
||||
//
|
||||
// Any fields in the request message which are not bound by the path
|
||||
// pattern automatically become (optional) HTTP query
|
||||
// parameters. Assume the following definition of the request message:
|
||||
//
|
||||
// ```proto
|
||||
// message GetMessageRequest {
|
||||
// string message_id = 1; // mapped to the URL
|
||||
// int64 revision = 2; // becomes a parameter
|
||||
// }
|
||||
// ```
|
||||
//
|
||||
// This enables a HTTP JSON to RPC mapping as below:
|
||||
//
|
||||
// HTTP | RPC
|
||||
// -----|-----
|
||||
// `GET /v1/messages/123456?revision=2` | `GetMessage(message_id: "123456" revision: 2)`
|
||||
//
|
||||
// Note that fields which are mapped to HTTP parameters must have a
|
||||
// primitive type or a repeated primitive type. Message types are not
|
||||
// allowed. In the case of a repeated type, the parameter can be
|
||||
// repeated in the URL, as in `...?param=A¶m=B`.
|
||||
//
|
||||
// For HTTP method kinds which allow a request body, the `body` field
|
||||
// specifies the mapping. Consider a REST update method on the
|
||||
// message resource collection:
|
||||
//
|
||||
// ```proto
|
||||
// service Messaging {
|
||||
// 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 {
|
||||
// string message_id = 1; // mapped to the URL
|
||||
// Message message = 2; // mapped to the body
|
||||
// }
|
||||
// ```
|
||||
//
|
||||
// NOTE: the notation `{message_id}` binds to the field `message_id` in the
|
||||
// corresponding method's request message.
|
||||
// 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 | RPC
|
||||
// -----|-----
|
||||
// `PUT /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:
|
||||
//
|
||||
// ```proto
|
||||
// service Messaging {
|
||||
// rpc UpdateMessage(Message) returns (Message) {
|
||||
// option (google.api.http) = {
|
||||
// put: "/v1/messages/{message_id}"
|
||||
// body: "*"
|
||||
// }
|
||||
// }
|
||||
// message Message {
|
||||
// string message_id = 2;
|
||||
// string text = 2;
|
||||
// }
|
||||
// ```
|
||||
//
|
||||
// The following HTTP JSON to RPC mapping is enabled:
|
||||
//
|
||||
// HTTP | RPC
|
||||
// -----|-----
|
||||
// `PUT /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 of
|
||||
// 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:
|
||||
//
|
||||
// ```proto
|
||||
// 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 | RPC
|
||||
// -----|-----
|
||||
// `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
|
||||
// The rules for mapping HTTP path, query parameters, and body fields
|
||||
// to the request message are as follows:
|
||||
//
|
||||
|
|
@ -186,8 +229,9 @@ message HttpRule {
|
|||
// 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.
|
||||
// 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).
|
||||
repeated HttpRule additional_bindings = 11;
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue