Chiebot-Mirror
/
googleapis
8
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update documentation on http annotation.

Browse Source
pull/2/head
wora 10 years ago
parent 3ee9064570
commit fc7061a35c
1 changed files with 117 additions and 73 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 190
      google/api/http.proto

190
google/api/http.proto
Unescape View File

@ -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 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 {
// rpc GetMessage(GetMessageRequest) returns (Message) {
// option (google.api.http).get = "/v1/messages/{message_id}";
// }
// }
// message GetMessageRequest {
// string message_id = 1; // mapped to the URL
// }
// message Message {
// string text = 1; // content of the resource
// }
// ```
//
// This definition enables an automatic, bidrectional mapping of HTTP
// JSON to RPC. Example:
//
// HTTP | RPC
// -----|-----
// `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`
//
// 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.
// 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
// }
// ```
// package example.messaging.v1;
//
// import "google/api/annotations.proto";
// import "google/protobuf/empty.proto";
// This enables a HTTP JSON to RPC mapping as below:
//
// service Messaging {
// // Standard List method.
// rpc ListMessages(ListMessagesRequest) returns (ListMessagesResponse) {
// option (google.api.http).get = "/v1/messages";
// // No body for HTTP GET.
// }
// HTTP | RPC
// -----|-----
// `GET /v1/messages/123456?revision=2` | `GetMessage(message_id: "123456" revision: 2)`
//
// // Standard Create method.
// rpc CreateMessage(CreateMessageRequest) returns (Message) {
// option (google.api.http) = {
// post: "/v1/messages"
// body: "message"
// };
// }
// 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&param=B`.
//
// // Standard Get method.
// rpc GetMessage(GetMessageRequest) returns (Message) {
// option (google.api.http).get = "/v1/messages/{message_id}";
// // No body for HTTP GET.
// }
// 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:
//
// // Standard Update method.
// ```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.
// }
// }
// message UpdateMessageRequest {
// string message_id = 1; // mapped to the URL
// Message message = 2; // mapped to the body
// }
// ```
//
// // A custom Forward method.
// rpc ForwardMessage(ForwardMessageRequest)
// returns (ForwardMessageResponse) {
// option (google.api.http) {
// post: "/v1/messages/{message_id}:forward"
// 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 text = 1;
// string message_id = 2;
// string text = 2;
// }
// ```
//
// message ListMessageRequest {
// }
// The following HTTP JSON to RPC mapping is enabled:
//
// message ListMesageResponse {
// repeated Message messages = 1;
// }
// HTTP | RPC
// -----|-----
// `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`
//
// message CreateMessageRequest {
// Message message = 1;
// }
//
// message GetMessageRequest {
// string message_id = 1;
// }
// 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.
//
// message UpdateMessageRequest {
// string message_id = 1;
// Message message = 2;
// }
// It is possible to define multiple HTTP methods for one RPC by using
// the `additional_bindings` option. Example:
//
// message DeleteMessageRequest {
// string message_id = 1;
// ```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 ForwardMessageRequest {
// message GetMessageRequest {
// string message_id = 1;
// string forward_address = 2;
// }
//
// message ForwardMessageResponse {
// string user_id = 2;
// }
// ```
//
// NOTE: the notation `{message_id}` binds to the field `message_id` in the
// corresponding method's request message.
// 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;
}

Write Preview
Loading…
Cancel
Save