Skip to content

ADR-0003: Use gRPC for Internal APIs and REST for Public API

  • Status: Accepted
  • Date: 2025-09-11
  • Authors: Senior Systems Analyst

Context and Problem Statement

In our microservices architecture (ADR-0002), we need a clear strategy for how services communicate with each other and how the outside world (our frontend) communicates with the system. We need a high-performance, low-latency solution for internal traffic and a well-understood, developer-friendly solution for the public-facing API.

Considered Options

  • Option 1: Use REST for All Communication

    • Description: All services, including the API Gateway, would communicate with each other using standard HTTP/JSON RESTful APIs.
    • Pros:
      • Consistent protocol across the entire system.
      • Easy to debug with standard tools (curl, Postman).
      • Wide developer familiarity.
    • Cons:
      • Can be less performant due to the overhead of HTTP/1.1 and text-based JSON serialization.
      • Lacks a formal, enforceable contract, leading to potential integration issues.

  • Option 2: Use gRPC for Internal APIs, REST for Public API (Chosen)

    • Description: The API Gateway exposes a standard RESTful API to the frontend. For all backend, server-to-server communication (e.g., API Gateway to AuthService), we will use gRPC.
    • Pros:
      • Performance: gRPC uses HTTP/2 and binary Protobuf serialization, making it significantly faster and more efficient for internal traffic.
      • Strict Contracts: The .proto files create a formal, strongly-typed contract between services, reducing integration errors.
      • Developer Experience (Frontend): The frontend team interacts with a standard, well-documented REST API, which is the industry standard for client-server communication.
      • Security: The internal gRPC services are not directly exposed to the public internet.
    • Cons:
      • Protocol Translation: The API Gateway now has the added responsibility of translating incoming REST requests into outgoing gRPC calls, and vice versa.
      • Tooling: gRPC can be more complex to debug than REST, requiring specific tools.

Decision

We will adopt a hybrid approach: gRPC for all internal, inter-service communication, and REST for the public-facing API exposed by the API Gateway. This decision optimizes for both internal performance and external developer-friendliness.

Consequences

Positive

  • Backend communication will be highly performant and efficient.
  • The formal gRPC contract will prevent entire classes of data-related bugs between services.
  • Frontend developers have a familiar and standard API to work with.

Negative

  • The API Gateway's logic becomes more complex as it must handle the REST-to-gRPC protocol translation. This is an acceptable trade-off for the performance and safety gains.