Mapping

DRAFT

Building HTTP REST APIs with gRPC

Nearly every HTTP REST API is backed by procedural code. This backing is done by code that maps incoming HTTP REST requests to procedure calls. With gRPC, this mapping is done by proxies, standalone processes that accept requests and handle them by calling backend gRPC services. As a result, those procedures can be distributed across a data center or anywhere on the Internet and they can be written in any of the ten languages with gRPC support.

Any HTTP REST API could conceivably be backed by gRPC services, but if an HTTP REST API follows a certain style, its mapping to gRPC can be handled automatically by standard gRPC tools.

These tools are configured by rules which define the mapping of an RPC method to one or more HTTP REST APIs. The mapping determines what portions of the gRPC request message (a Protocol Buffer) are populated from the path, query parameters, or body of the HTTP request.

A Simple Example

The mapping is specified with the HTTP method name and a path template. The path template can refer to fields in the request message, as in the example below which describes a REST GET operation on a collection of messages:

service Messaging {
  rpc GetMessage(GetMessageRequest) returns (Message) {
    option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";
  }
}
message GetMessageRequest {
  message SubMessage {
    string subfield = 1;
  }
  string message_id = 1; // mapped to the URL
  SubMessage sub = 2;    // `sub.subfield` is url-mapped
}
message Message {
  string text = 1; // content of the resource
}

Here the HTTP mapping is specified in the google.api.http option, but it can also be expressed inside the GRPC API Configuration YAML file.

http:
  rules:
    - selector: <proto_package_name>.Messaging.GetMessage
      get: /v1/messages/{message_id}/{sub.subfield}

This enables an automatic mapping of HTTP requests to the GetMessage RPC.

Example:

HTTP	RPC
GET /v1/messages/123456/foo	GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))

Both fields and 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.

Request Fields Automatically Correspond to Query Parameters

Any fields in the request message which are not bound by the path pattern automatically become optional HTTP query parameters.

As an example, assume the following definition of the request message:

message GetMessageRequest {
  message SubMessage {
    string subfield = 1;
  }
  string message_id = 1; // mapped to the URL
  int64 revision = 2;    // becomes a parameter
  SubMessage sub = 3;    // `sub.subfield` becomes a parameter
}

It enables this HTTP JSON to RPC mapping:

HTTP	RPC
GET /v1/messages/123456?revision=2&sub.subfield=foo	GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield: "foo"))

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.

Use the body Field to Specify Request Bodies

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:

service Messaging {
  rpc UpdateMessage(UpdateMessageRequest) returns (Message) {
    option (google.api.http) = {
      put: "/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 standard Protocol Buffer JSON encoding:

HTTP	RPC
PUT /v1/messages/123456 { "text": "Hi!" }	UpdateMessage(message_id: "123456" message { text: "Hi!" })

Use body: "*" to Map All Unspecified Fields To The Request Body

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) = {
      put: "/v1/messages/{message_id}"
      body: "*"
    };
  }
}
message Message {
  string message_id = 1;
  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.

Use additional_bindings to Map Multiple HTTP REST Calls to a Single RPC Handler

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	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:

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 ;

The syntax * matches a single path segment. It follows the semantics of RFC 6570 Section 3.2.2 Simple String Expansion.

The syntax ** matches zero or more path segments. It follows the semantics of RFC 6570 Section 3.2.3 Reserved Expansion. NOTE: it must be the last segment in the path except the Verb. The syntax LITERAL matches literal text in the URL path. The syntax Variable matches the entire path as specified by its template; this nested template must not contain further variables. If a variable matches a single path segment, its template may be omitted, e.g. {var} is equivalent to {var=*}.

NOTE: the field paths in variables and in the body must not refer to repeated fields or map 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.

DRAFT