Hexagonal Architecture with REST and gRPC in Microservices

Core Idea

Examples and diagrams in this page follow the shared Hypothetical Scenario.

Microservice teams often face a protocol split. External consumers need broad compatibility and stable web contracts. Internal services need low latency, strict typing, and predictable interoperability. One protocol for every boundary usually creates trade-offs that hurt either external usability or internal performance.

Hexagonal Architecture gives a clean way to solve this split. The core use case model stays protocol-agnostic. Inbound and outbound adapters handle protocol-specific concerns. This allows one service to expose REST at the edge and use gRPC for internal service interactions without contaminating domain policy.

In the handbook scenario, user-facing recommendation queries and marketplace actions can use REST contracts. Internal scoring, pricing, and reliability services can use gRPC contracts. Hexagonal boundaries keep both channels consistent with the same domain rules.

Historical Context

Hexagonal Architecture was introduced by Alistair Cockburn in 2005 to decouple business behavior from delivery and infrastructure details. REST constraints were formalized by Roy Fielding in 2000 and became dominant for web-facing contracts. gRPC and Protocol Buffers became mainstream in 2015 for typed service-to-service communication. Modern microservice systems now combine these styles through explicit boundary design.

Sources: Fielding (2000), Cockburn (2005), and Google Open Source (2015)

The Problem It Solves

Many microservice programs drift into mixed protocol logic. A controller contains domain decisions and transport mapping. A gRPC handler reaches directly into persistence models. Validation rules differ by entry channel. The same capability behaves differently across REST and gRPC calls.

This creates recurring engineering pain.

• duplicated policy logic in multiple handlers
• inconsistent error semantics across protocols
• high regression risk during contract changes
• slow protocol migrations due to deep coupling
• weak testability at boundary contracts

A clear split between north-south and east-west traffic helps. North-south traffic is external client traffic that crosses the platform edge. East-west traffic is internal service-to-service traffic inside the platform. These traffic classes have different constraints. Hexagonal Architecture allows distinct adapters for each traffic class while keeping one coherent core behavior model.

Main Concept

The key design pattern is channel-specific adapters over shared ports.

Shared Core, Multiple Inbound Adapters

A microservice defines driving ports for each use case. REST controllers and gRPC handlers are both inbound adapters that call the same port contracts. Both channels convert protocol payloads into domain commands. Both channels receive core outcomes and map them back to channel response models.

REST at the Service Edge

REST is usually a strong fit for public or partner-facing contracts. Benefits include:

• broad client interoperability
• easy debugging and observability tooling
• cache and HTTP semantics for read-heavy paths

REST adapters should own:

• HTTP status mapping
• header policy
• request validation at transport shape level
• representation versioning policy

gRPC for Internal Service Calls

gRPC is usually a strong fit for east-west interactions where latency and type consistency matter. Benefits include:

• generated clients from protobuf contracts
• compact payloads and low serialization overhead
• clear timeout and metadata patterns

gRPC adapters should own:

• protobuf message mapping
• gRPC status and error details mapping
• deadline and retry policy hooks
• metadata propagation for trace and identity

Consistency Rule Across Protocols

The business outcome for one use case must remain equivalent across channels. Protocol differences should affect transport semantics only. They should not alter domain policy results.

For the scenario, the GenerateRecommendationBrief capability should enforce the same eligibility and budget rules whether called through REST or gRPC. Contract shape can differ. Policy outcome must remain aligned.

The diagram shows REST and gRPC inbound adapters calling shared use case ports in one service core.

How It Works

A practical implementation model for one microservice:

Step 1. Define use case ports in domain language. Example: GenerateRecommendationBriefPort, ReserveListingPort, GetOwnershipCostPort.

Step 2. Implement use case services in the application ring. These services orchestrate domain policy and driven ports.

Step 3. Implement REST inbound adapters for edge capabilities. Expose resource-oriented endpoints and stable representation policies.

Step 4. Implement gRPC inbound adapters for internal high-frequency calls where needed. Expose protobuf service contracts mapped to the same use case ports.

Step 5. Implement driven ports for persistence, messaging, and external providers. Adapters for database, queue, and partner APIs remain protocol-agnostic from the core view.

Step 6. Standardize error taxonomy at the core. Map core error classes to REST and gRPC transport semantics in adapters.

Step 7. Add contract tests per protocol. REST contract tests verify status and representation rules. gRPC contract tests verify protobuf compatibility and status mapping.

Step 8. Add behavior equivalence tests. The same input through REST and gRPC paths should produce equivalent domain outcomes.

Step 9. Add observability consistency. Trace correlation IDs should link cross-protocol calls in one request chain.

Step 10. Apply rollout policy. Expose new internal capabilities in gRPC first for service mesh calls, then expose selected capabilities in REST for external consumption when needed.

Example Capability Split in the Scenario

• REST edge capabilities:
• user profile onboarding
• recommendation brief retrieval

• marketplace listing browse and reserve actions

• gRPC internal capabilities:

• reliability score retrieval
• ownership-cost component aggregation

• market-price normalization and scoring

• shared core policies:

• budget and preference constraints
• ranking invariants
• reservation eligibility rules

The diagram shows north-south REST edge flow and east-west gRPC internal flow around shared domain ports.

Challenges and Shortcomings

This model gives clear benefits and real operational cost.

Common risks:

• duplicate mapping layers with weak automation
• drift in validation rules between REST and gRPC adapters
• inconsistent observability metadata across channels
• transport-specific optimizations leaking into domain use cases
• versioning complexity when both protocols evolve under different cadences

Governance is required. Teams need shared error taxonomy, mapping guidelines, and contract review gates. Without governance, channel divergence can reappear and erase the benefits.

This model is not required for every service. A simple service with one channel may not justify dual protocol exposure. High-value services with both external and internal traffic usually gain strong long-term value from this split.

Link to Existing Handbook Concepts

Written by: Pedro Guzmán

See References for complete APA-style bibliographic entries used on this page.