The Importance of REST Integration

There are several compelling reasons to allow clients to consume gRPC APIs via HTTP/REST rather than through the gRPC protocol:

1. Client Compatibility:

   Not all clients support gRPC. For instance, web browsers and certain mobile environments have limited gRPC support. By offering an HTTP/REST interface, you can extend access to these clients.

2. Interoperability:

   HTTP/REST is a universally recognized standard, compatible with nearly every programming language and platform. This interface enhances the interoperability of your gRPC services across various systems and technologies.

3. User-Friendliness:

   APIs designed around HTTP/REST can be more straightforward for developers who are less familiar with gRPC. Tools such as curl facilitate direct command-line calls, and numerous resources exist for testing and documenting HTTP/REST APIs.

4. Network Limitations:

   Certain networks and firewalls may restrict gRPC traffic due to its reliance on HTTP/2, which is not universally supported. Conversely, HTTP/REST operates on HTTP/1.1, making it widely acceptable.

By utilizing a tool like gRPC-Gateway, you can leverage the advantages of both worlds: the robustness and efficiency of gRPC for compatible clients, along with the accessibility of HTTP/REST for those that are not.

How gRPC-Gateway Works

To understand how REST and gRPC communicate, consider the following process facilitated by the gRPC-Gateway:

1. A client sends an HTTP request to the gRPC-Gateway.
2. The gRPC-Gateway translates this HTTP request into a gRPC request and forwards it to the gRPC server.
3. The gRPC server processes the request and sends a gRPC response back to the gRPC-Gateway.
4. The gRPC-Gateway converts this gRPC response into an HTTP response and returns it to the client.

To generate code for both gRPC and REST interfaces based on your protobuf definitions, you can configure the buf.gen.yaml file to include both the go-grpc and grpc-gateway plugins.

version: v1

managed:

enabled: true

go_package_prefix:

default: eda-in-golang/baskets/basketspb

except:

• buf.build/googleapis/googleapis

plugins:

• name: go

  out: .

  opt:

  • paths=source_relative

• name: go-grpc

  out: .

  opt:

  • paths=source_relative

• name: grpc-gateway

  out: .

  opt:

  • paths=source_relative
  • grpc_api_configuration=internal/rest/api.annotations.yaml

• name: openapiv2

  out: internal/rest

  opt:

  • grpc_api_configuration=internal/rest/api.annotations.yaml
  • openapi_configuration=internal/rest/api.openapi.yaml
  • allow_merge=true
  • merge_file_name=api

The gRPC-Gateway plugin creates a reverse-proxy server that converts a RESTful HTTP API into gRPC. Clients can send HTTP requests to your gRPC service through this setup. The grpc_api_configuration option references a file (internal/rest/api.annotations.yaml) that provides additional configurations for the gRPC-Gateway.

The api.annotations.yaml file specifies how HTTP requests are mapped to gRPC method calls. The http.rules section contains an array of rules outlining this mapping. The selector indicates the gRPC method associated with a rule, while the HTTP methods (post, get, delete, put) specify the corresponding paths for requests. For instance, a POST request to /api/baskets would translate into a call to the StartBasket method in the BasketService.

This configuration allows clients limited to HTTP to interact with your gRPC service effectively. Additionally, the OpenAPI specification outlines the HTTP interface these clients should follow.