18 Gateway

In this tutorial, you will learn about grpc. We cover key concepts, practical examples, and best practices to help you master this topic.

gRPC-Gateway generates a reverse proxy that exposes gRPC services as RESTful JSON APIs. It reads proto annotations to map HTTP methods, paths, and query parameters to gRPC RPC methods, enabling both gRPC and REST access to the same service.

What You'll Learn

• HTTP annotations in proto files (google.api.http)
• Generating the gateway reverse proxy
• HTTP path and query parameter mapping
• Serving gRPC and REST on the same port
• Customizing HTTP responses

Why It Matters

Many clients cannot use gRPC directly (browsers, legacy systems, third-party integrations). gRPC-Gateway provides RESTful access without maintaining separate REST endpoints.

Real-World Use

Google Cloud APIs use grpc-gateway for REST endpoints alongside gRPC. The etcd project uses gateways. CNCF projects like Vitess and gRPC-Gateway itself use this pattern.

flowchart LR
    REST[HTTP Client] -->|JSON Request| Gateway[gRPC-Gateway]
    Gateway -->|gRPC Call| Server[gRPC Server]
    Server -->|gRPC Response| Gateway
    Gateway -->|JSON Response| REST
    Native[Native gRPC Client] -->|gRPC| Server

Teacher Mindset

gRPC-Gateway does not modify your gRPC server. It adds a proxy in front that translates REST requests to gRPC calls. This gives you both protocols from one server implementation.

Code Examples

// Example 1: Proto with HTTP annotations
import "google/api/annotations.proto";

service OrderService {
  rpc GetOrder (GetOrderRequest) returns (Order) {
    option (google.api.http) = {
      get: "/v1/orders/{order_id}"
    };
  }

  rpc ListOrders (ListOrdersRequest) returns (ListOrdersResponse) {
    option (google.api.http) = {
      get: "/v1/orders"
    };
  }

  rpc CreateOrder (CreateOrderRequest) returns (Order) {
    option (google.api.http) = {
      post: "/v1/orders"
      body: "*"
    };
  }
}

// Example 2: Advanced HTTP mapping
service ProductService {
  rpc UpdateProduct (UpdateProductRequest) returns (Product) {
    option (google.api.http) = {
      patch: "/v1/products/{product.id}"
      body: "product"
    };
  }

  rpc DeleteProduct (DeleteProductRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1/products/{id}"
    };
  }

  rpc SearchProducts (SearchProductsRequest) returns (stream Product) {
    option (google.api.http) = {
      get: "/v1/products/search"
    };
  }
}

# Example 3: Generate and run the gateway
# Generate gRPC-Gateway code
protoc -I . --grpc-gateway_out . \
  --grpc-gateway_opt logtostderr=true \
  --grpc-gateway_opt paths=source_relative \
  proto/order_service.proto

# Start server and gateway
go run main.go  # Starts gRPC server on :50051
go run gateway.go  # Starts gateway on :8080

# Test via REST
curl http://localhost:8080/v1/orders/123
curl -X POST http://localhost:8080/v1/orders \
  -d '{"customer_id": "456", "items": [{"product_id": "789", "quantity": 2}]}'

Common Mistakes

• Not importing google/api/annotations.proto in the proto file
• Forgetting to add the body clause in POST/PATCH annotations
• Using query parameters that do not match proto field types
• Not handling HTTP status code mapping from gRPC errors
• Ignoring CORS configuration when serving REST to browser clients

Practice

1. Add HTTP annotations to your order service proto file.
2. Generate the gateway code using protoc.
3. Start both the gRPC server and gateway.
4. Test GET and POST endpoints with curl.
5. Challenge: Add a custom HTTP response header mapping using google.api.http annotations.

FAQ

Mini Project

Generate a gRPC-Gateway for your order service. Add HTTP annotations for GetOrder (GET), ListOrders (GET), CreateOrder (POST), and UpdateOrder (PATCH). Test all endpoints with curl. Generate OpenAPI documentation.

What's Next

Next, you will learn about testing gRPC services with unit and integration tests.