Exploring the Power of gRPC-Gateway for Writing RESTful Services

30th June 2026

Agenda

• What is gRPC-Gateway
• How gRPC-Gateway works
• Ways to do gRPC Gateway HTTP Mapping
• How to write simple hello world service using gRPC-Gateway
• Advanced features gRPC-Gateway provides
• Key Takeaways
• References

Speaker - Rajiv Ranjan Singh

x.com/therajiv

• Software Engineer (JL3) at A.P. Moller Maersk
• Graduated from JSSATE, Bengaluru, India
• GSoC 2022, LFX Mentorship 2021, and GSoD 2020 & 2021
• Mentored in GSoC 2023, 2024, 2025, and 2026 with Jenkins
• Previously worked with Lummo, redBus, and Economize

What is gRPC-Gateway

• A protoc plugin that generates a reverse-proxy server which translates RESTful HTTP API into gRPC

• Generate REST API from protobuf definitions

• Serve both gRPC and REST from the same service

• Multiple ways to do HTTP mappings

• Automatic OpenAPI/Swagger documentation

How gRPC-Gateway works

1. Client sends HTTP/JSON request
2. gRPC-Gateway proxy receives request
3. Proxy translates to gRPC call
4. gRPC service processes request
5. Response flows back through proxy
6. Client receives HTTP/JSON response

How gRPC-Gateway works

Ways to do gRPC Gateway HTTP Mapping

• Method 1: Inline Annotations
• Method 2: External gRPC API Configuration (YAML File)
• Method 3: Unannotated Methods (Auto-generate)
• Method 4: Multiple HTTP Bindings (Advanced)

Method 1: Inline Annotations

Method 2: External gRPC API Configuration (YAML File)

type: google.api.Service
config_version: 3

http:
  rules:
    - selector: hello.v1.GreeterService.SayHello
      post: /v1/hello
      body: "*"

Method 3: Unannotated Methods (Auto-generate)

• No annotations or YAML files needed
• Auto-generates endpoints based on service/method names
• Best for quick prototyping and internal APIs

Method 4: Multiple HTTP Bindings (Advanced)

How to write simple hello world service using gRPC-Gateway

• Define gRPC service in proto file
• Add HTTP annotations for REST mapping
• Generate code stubs using buf
• Implement and run both gRPC and REST servers

Step 1: Define the Service (proto/hello.proto)

Step 2: Configure buf (buf.yaml)

version: v2
modules:
  - path: proto
    name: buf.build/wearedevelopers-world-congress-europe-2026/hello
deps:
  - buf.build/googleapis/googleapis
lint:
  use:
    - STANDARD
    - FILE_LOWER_SNAKE_CASE
  ignore:
    # Ignore the response naming convention for streaming RPCs
    - RPC_RESPONSE_STANDARD_NAME

Step 3: Configure Code Generation (buf.gen.yaml)

version: v2
managed:
  enabled: true
  disable:
    - module: buf.build/googleapis/googleapis
  override:
    - file_option: go_package_prefix
      value: github.com/iamrajiv/wearedevelopers-world-congress-europe-2026/examples/hello/gen/proto
plugins:
  - remote: buf.build/protocolbuffers/go:v1.36.11
    out: gen/proto
    opt:
      - paths=source_relative
  - remote: buf.build/grpc/go:v1.5.1
    out: gen/proto
    opt:
      - paths=source_relative
  - remote: buf.build/grpc-ecosystem/gateway:v2.29.0
    out: gen/proto
    opt:
      - paths=source_relative

Step 4: Implement the Server (main.go)

type server struct {
    hellopb.UnimplementedGreeterServiceServer
}

Step 5: Start gRPC Server

func runGRPCServer() error {
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        return fmt.Errorf("failed to listen: %v", err)
    }

    grpcServer := grpc.NewServer()
    hellopb.RegisterGreeterServiceServer(grpcServer, &server{})

    // Register reflection service for grpcurl
    reflection.Register(grpcServer)

    log.Println("gRPC server listening on :50051")
    if err := grpcServer.Serve(lis); err != nil {
        return fmt.Errorf("failed to serve gRPC: %v", err)
    }
    return nil
}

Step 6: Start REST Gateway

func runRESTGateway() error {
    ctx := context.Background()
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    // Create gRPC-Gateway mux
    mux := runtime.NewServeMux()

    // Register the service handler
    opts := []grpc.DialOption{grpc.WithTransportCredentials(insecure.NewCredentials())}
    err := hellopb.RegisterGreeterServiceHandlerFromEndpoint(ctx, mux, "localhost:50051", opts)
    if err != nil {
        return fmt.Errorf("failed to register gateway: %v", err)
    }

    // Start HTTP server
    log.Println("gRPC-Gateway (REST) server listening on :8080")
    if err := http.ListenAndServe(":8080", mux); err != nil {
        return fmt.Errorf("failed to serve REST: %v", err)
    }
    return nil
}

Testing the Service

gRPC Client Test:

grpcurl -plaintext \
  -d '{"name": "WeAreDevelopers"}' localhost:50051 hello.v1.GreeterService/SayHello

REST Client Test:

curl -X POST http://localhost:8080/v1/hello \
  -H "Content-Type: application/json" -d '{"name": "WeAreDevelopers"}'

Both Return:

{
  "message": "Hello, WeAreDevelopers!"
}

Advanced features gRPC-Gateway provides

• Custom HTTP Mapping
• Streaming Support
• Error Handling

Advanced features gRPC-Gateway provides - Custom HTTP Mapping

Advanced features gRPC-Gateway provides - Streaming Support

service GreeterService {
  rpc StreamGreetings(StreamRequest) returns (stream HelloResponse) {
    option (google.api.http) = {
      get: "/v1/greetings/stream"
    };
  }
}

Returns: NDJSON (newline-delimited JSON) streaming over HTTP using chunked transfer encoding

Streaming Support:

• Server-side streaming → NDJSON over HTTP (each gRPC message → JSON → flushed immediately)
• Client-side streaming → gRPC native clients only (REST cannot stream requests)
• Bidirectional streaming → gRPC native clients only (requires HTTP/2 duplex)

Advanced features gRPC-Gateway provides - Error Handling

func (s *server) GetUser(ctx context.Context, req *GetUserRequest) (*User, error) {
    // Simulate database lookup
    user, err := s.db.QueryRowContext(ctx, "SELECT user_id, name, email, created_at FROM users WHERE user_id = ?", req.UserId).Scan()

    // Handle not found error
    if err == sql.ErrNoRows {
        return nil, status.Errorf(codes.NotFound, "user %s not found", req.UserId)
    }

    // Handle database errors
    if err != nil {
        return nil, status.Errorf(codes.Internal, "database error: %v", err)
    }

    // Validate user data
    if user == nil {
        return nil, status.Error(codes.InvalidArgument, "invalid user data")
    }

    return user, nil
}

Advanced features gRPC-Gateway provides - Error Handling

Translation:

• codes.NotFound → HTTP 404
• codes.InvalidArgument → HTTP 400
• codes.Internal → HTTP 500

Key Takeaways

• gRPC-Gateway bridges gRPC and REST automatically
• Write your service once, serve both protocols
• Internal services get gRPC performance
• External clients get REST compatibility
• Free OpenAPI documentation
• Production-ready and battle-tested
• Huge time-saver for API development

References

• github.com/grpc-ecosystem/grpc-gateway
• grpc-ecosystem.github.io
• github.com/iamrajiv/wearedevelopers-world-congress-europe-2026
• protobuf.dev
• grpc.io
• buf.build

Thank you