Skip to main content
Version: Next

Json Transcoder

danger

This guide was generated by ChatGPT. All content in this guide was generated by ChatGPT and should not be considered as professional advice or recommendations. Use at your own risk.

Introduction to JSON Transcoding of google/api/http.proto​

JSON transcoding of google/api/http.proto provides a simple and flexible way to bridge the gap between gRPC APIs and HTTP APIs. The google/api/http.proto file defines a set of annotations that allow users to describe how HTTP requests and responses should be mapped to corresponding gRPC requests and responses.

One of the main advantages of using JSON transcoding is that it allows gRPC services to be easily exposed as HTTP/JSON endpoints, making it easier for developers to build web applications and integrate gRPC services with existing HTTP/JSON-based systems.

Rules for JSON Transcoding​

In order to effectively use JSON transcoding, it is important to understand the various rules that govern how HTTP requests and responses are mapped to corresponding gRPC requests and responses. The following are some of the key rules to keep in mind:

Rule 1: HTTP Methods​

HTTP methods (GET, POST, PUT, DELETE, etc.) are mapped to gRPC method names using the google.api.http annotation. For example, the following annotation specifies that an HTTP GET request should be mapped to a gRPC method called GetBook:

rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{name=shelves/*/books/*}"
  };
}

Rule 2: Request and Response Types​

HTTP requests and responses are mapped to gRPC requests and responses using the request and response message types defined in the gRPC service. For example, the following annotation specifies that an HTTP GET request should be mapped to a gRPC request message of type GetBookRequest and a gRPC response message of type Book:

rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{name=shelves/*/books/*}"
  };
}

Rule 3: URI Parameters​

URI parameters in HTTP requests can be mapped to fields in the gRPC request message using the google.api.http annotation. For example, the following annotation specifies that an HTTP GET request should include a parameter called name in the URI, which will be mapped to a field called name in the gRPC request message:

rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{name=shelves/*/books/*}"
  };
}

Rule 4: Query Parameters​

Query parameters in HTTP requests can be mapped to fields in the gRPC request message using the google.api.http annotation. For example, the following annotation specifies that an HTTP GET request should include a query parameter called language in the URI, which will be mapped to a field called language in the gRPC request message:

rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{name=shelves/*/books/*}?language={language}"
  };
}

Rule 5: Request Body​

HTTP request bodies can be mapped to fields in the gRPC request message using the google.api.http annotation. For example, the following annotation specifies that an HTTP POST request should include a JSON-encoded request body, which will be mapped to a field called book in the gRPC request message:

rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/shelves/{shelf}/books",
    body: "book"
  };
}

Rule 6: Response Body​

HTTP response bodies can be represented in a number of different ways, including plain text, HTML, JSON, and binary data. When using the JSON transcoder, the response body must be represented as a JSON object. The JSON object can contain any number of fields, each of which corresponds to a particular piece of data in the response.

For example, consider the following HTTP response body:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "1234",
  "name": "John Smith",
  "email": "john.smith@example.com"
}

In this response, the JSON object contains three fields: id, name, and email. Each field corresponds to a particular piece of data in the response.

When defining a mapping from a gRPC service to an HTTP service using the JSON transcoder, it is important to specify how the gRPC response should be mapped to the HTTP response body. This can be done using the response_body field in the mapping configuration.

For example, consider the following mapping configuration:

http:
  rules:
  - selector: example.v1.ExampleService.GetExample
    get: /v1/example/{id}
    body: "*"
    response_body: "data"

In this configuration, the response_body field is set to data. This means that the response body of the HTTP response should be a JSON object containing a single field called data. The value of the data field should be the serialized response message from the gRPC service.

It is also possible to map specific fields in the response message to fields in the HTTP response body. This can be done using the field_mapping field in the mapping configuration.

For example, consider the following mapping configuration:

http:
  rules:
  - selector: example.v1.ExampleService.GetExample
    get: /v1/example/{id}
    body: "*"
    response_body: "data"
    field_mapping:
      "data.id": "id"
      "data.name": "name"
      "data.email": "email"

In this configuration, the response_body field is set to data, just like in the previous example. However, in addition to this, the field_mapping field is used to map the id, name, and email fields from the gRPC response message to fields in the HTTP response body.

By using the JSON transcoder and specifying the appropriate mapping configuration, it is possible to easily convert between gRPC and HTTP APIs. This can be a powerful tool for building scalable and interoperable systems.

Resources​