ADR-26-01: Gravitee API Gateway as CS CoE Standard for Internal API Management

Status

Proposed

Impact

High

Demand Owner

Matthieu Croissant

ADR Contributors

Christian Blumenroehr, Matthieu Croissant, Prasad Ramachandran, Justin Taylor

Reviewers

DDC Architecture Council, Extended Architecture Team

Informed

Architecture Council

Publication Date

January 15, 2026

📋 Executive Summary

This Architecture Decision Record (ADR) documents the decision to adopt Gravitee API Gateway as the standard API management platform for internal API exposure across the CS CoE (Computational Sciences Center of Excellence). This decision applies to both pRED and gRED capabilities and establishes Gravitee as the recommended solution for teams developing and exposing internal APIs within the Roche network.

Decision: All new internal API projects within CS CoE MUST use Gravitee API Gateway. Existing APIs are encouraged but not mandated to migrate.

📗 Background

The Computational Sciences Center of Excellence (CS-CoE) was established to unify and modernize the computation and data ecosystems across Roche’s Research and Early Development (RED) organizations, including pRED and gRED. The connectivity of the various systems, applications, and data sources is crucial to enable seamless data flow, integration, and AI-driven scientific innovation. The sheer volume and variety of APIs required to support these integrations necessitate a robust API management solution.

In the past years part of the organization has onboarded and uses Gravitee as its API management solution. However, with the formation of the CS-CoE, there is a need to evaluate whether Gravitee remains the best fit for the combined organization and will meet the evolving requirements.

ℹ️ Context

Current Landscape

The CS CoE currently operates in a fragmented API management environment:

  • pRED: Successfully deployed Gravitee with 400+ APIs registered, demonstrating production viability

  • gRED: Limited Gravitee adoption, with teams using ad-hoc solutions or no centralized API management

  • Platform Maturity: Gravitee infrastructure is production-ready, C4-approved (Secret data), and hosted on US & EU cloud instances

Problem Statement

Without a standardized API management platform, CS CoE faces:

  1. Poor API Discoverability: No centralized catalog makes it difficult for developers to find and consume existing APIs

  2. Duplicated Effort: Teams rebuild common capabilities (rate limiting, monitoring, documentation) instead of leveraging shared infrastructure

  3. Operational Overhead: Multiple point solutions increase maintenance burden and training requirements

  4. Limited Observability: Lack of centralized analytics and monitoring makes troubleshooting and optimization difficult

Business Drivers

  • Architecture Standardization: DDC Architecture Council mandate to establish consistent patterns across CS CoE

  • Developer Experience: Centralized API catalog reduces time-to-integration for consuming teams

  • Operational Efficiency: Shared platform reduces per-team operational overhead

  • Strategic Alignment: Supports broader digital transformation and microservices adoption initiatives

🌈 Consequences

The CS CoE face the need to choose an API management solution that balances developer experience, security, operational efficiency, and strategic alignment. Multiple options are available with varying trade-offs: 1. Status Quo (Gravitee + Team Choice) 2. MuleSoft for All APIs 3. Adopt Gravitee overall

🤝 Outcome / Decision

Scope and Applicability

Gravitee API Gateway is endorsed as the standard platform for internal API management within CS CoE.

MUST Use Gravitee (Mandatory)

  • New API Projects: All new consumer-facing and cross-team internal APIs developed within CS CoE, those API backends should prevent direct access by-passing Gravitee. New APIs must use Gravitee unless there’s a documented exception (e.g., external APIs, sub milliseconds requirements)

  • Greenfield Microservices: New service-oriented architectures

  • API Modernization: Legacy APIs being refactored (e.g., SOAP to REST migrations)

  • API consumer must call through the gateway to access the API

SHOULD Use Gravitee (Recommended)

  • Existing Stable APIs: Legacy APIs in maintenance mode with no planned changes

  • Low-Volume APIs: Internal team APIs with <5 consumers and no growth plans

MUST NOT Use Gravitee (Exceptions)

  • Point-to-Point Integration: Direct database access or file transfers where API pattern doesn’t apply

  • Embedded Systems: IoT devices or edge computing where gateway overhead is prohibitive

  • Massive Data Transfer: High-throughput data pipelines (e.g., bulk ETL jobs)

  • External APIs: APIs exposed to public internet or external partners (use MuleSoft via Proxify instead)

  • Service meshes calls within a single application boundary (defined as services within the same Kubernetes namespace owned by the same team and sharing a common security context) may use direct internal routing (e.g., service mesh) where justified, provided mutual TLS/workload identity is enforced and authorization responsibilities are clearly defined.

CORE Capabilities (MUST Use) - Directly Addresses Problem Statement

These capabilities are mandatory and directly solve the identified problems:

Capability Problem Addressed Implementation Requirement

API Catalog & Discovery

Poor API Discoverability

All APIs MUST be registered in Gravitee’s catalog with OpenAPI/Swagger documentation

API Gateway Routing

Operational Overhead, Duplicated Effort

All consumer traffic MUST route through Gravitee (not direct backend access)

Authentication (OAuth2, API Keys)

Centralized auth for APIs

Validation of oAuth Tokens enforced at Gravitee layer, API keys are issued by Gravitee

Centralized Monitoring & Analytics

Limited Observability

Teams MUST use Gravitee’s built-in analytics dashboard for API usage metrics

API Documentation Portal

Poor Discoverability, Duplicated Effort

API documentation MUST be published via Gravitee’s developer portal

RECOMMENDED Capabilities (SHOULD Use) - Add Value But Not Mandatory

These capabilities are strongly recommended and add significant value, but teams may have existing solutions:

Capability Benefit Alternative Acceptable

Rate Limiting & Quotas

Prevents API abuse, protects backend services

Custom implementation in application code (not recommended)

Request/Response Transformation

Enables API versioning without backend changes

Backend handles transformation (less flexible)

Caching

Reduces backend load, improves performance

Backend caching or CDN (complementary)

CORS Configuration

Browser-based API consumption

Configure in backend if simpler for your use case

OUT OF SCOPE - Use Other Tools

These are explicitly NOT recommended to be implemented in Gravitee:

Capability Recommended Alternative

Authorization & RBAC

For fine-grained access control use application-level authorization

Service-to-Service Authentication within Kubernetes

Use service mesh (Istio, Linkerd) for mTLS

Infrastructure Load Balancing

Use existing load balancers (nginx, HAProxy, F5)

Positioning: Gravitee vs. MuleSoft

Dimension Gravitee MuleSoft

Primary Use Case

Internal API exposure within Roche network

External API exposure to public internet

Target Consumers

pRED/gRED teams, internal applications

External partners, public applications

Security Context

Internal security controls, C4-compatible

DMZ placement, hardened for external threats

Deployment Model

Self-service, developer-centric

Centralized, requires MuleSoft expertise

Time to Market

Fast (hours)

Slower (days)

API Catalog

https://gravitee.roche.com/

Separate portal https://developer.roche.com/s/apis

Recommendation: Use Proxify to expose existing internal APIs externally via MuleSoft rather than re-implementing in MuleSoft directly.

Architectural Positioning

Gravitee functions as an API Management Platform operating at the L7 (Application Layer) of the network stack. It is not a replacement for existing infrastructure but rather a management and policy enforcement layer that sits in front of your backend services.

Network Architecture

graph TB
    Consumer["🌐 API Consumer<br/>(Mobile App, Web App, Microservice)"]

    subgraph Gravitee["Gravitee API Gateway (L7)"]
        Auth["🔐 Authentication<br/>(OAuth2, API Keys, OIDC)"]
        RateLimit["⏱️ Rate Limiting & Quotas"]
        Transform["🔄 Request/Response Transformation"]
        Analytics["📊 API Analytics & Monitoring"]
        Catalog["📚 API Catalog & Discovery"]
    end

    subgraph Existing["Your Existing Infrastructure (Optional)"]
        LB["⚖️ Load Balancer"]
        Mesh["🕸️ Service Mesh"]
        Ingress["🚪 Ingress Controller"]
    end

    Backend["⚙️ Backend Service<br/>(REST API, Microservice, Legacy System)"]

    Consumer --> Gravitee
    Gravitee --> Existing
    Existing --> Backend

    style Gravitee fill:#e1f5ff,stroke:#0288d1,stroke-width:2px
    style Existing fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style Consumer fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style Backend fill:#e8f5e9,stroke:#388e3c,stroke-width:2px

Trade-offs and Accepted Costs

This decision accepts the following trade-offs in exchange for centralized governance and consistency:

Trade-off Cost Benefit

Additional Network Hop

3-10ms latency per API call

Centralized monitoring, rate limiting, and security policies

Gateway Dependency

Single point of failure (mitigated by multi-region deployment)

Consistent authentication, API catalog, and governance

Migration Effort

Time investment to onboard existing APIs (1 day per API)

Long-term reduction in duplicated tooling and support burden

Learning Curve

Teams must learn Gravitee platform (1-2 days training)

Standardized approach reduces fragmentation and knowledge silos

Net Assessment: The governance, discoverability, and operational efficiency gains justify the accepted latency and migration costs for most internal APIs.

What Gravitee Is

  • API Management Platform: Provides discovery, governance, security, and analytics

  • L7 Proxy: Routes requests based on HTTP headers, paths, and methods

  • Policy Enforcement Point: Applies cross-cutting concerns (auth, rate limiting, transformation)

  • Developer Portal: Centralized catalog for API discovery and self-service subscription

What Gravitee Is NOT

  • Not a Load Balancer: Use nginx/HAProxy/F5 for traffic distribution across instances

  • Not a Service Mesh: Use Istio/Linkerd for service-to-service communication within clusters

  • Not a Replacement: Gravitee sits in front of your existing infrastructure, adding management capabilities

Rationale

Production-Proven at Scale

  • 400+ APIs successfully deployed in pRED

  • C4 security approval enables transit of secret data over the gateway

  • Enterprise-grade infrastructure (Nebula/Minerva hosting, multi-region availability)

  • Vendor support and established operational model

Developer Experience & Self-Service

  • API Catalog: Centralized discovery portal at https://gravitee.roche.com/

  • Self-Service Onboarding: Teams can publish and subscribe to APIs independently

  • Rich Documentation: Built-in API documentation with OpenAPI/Swagger support

  • Developer Portal: Interactive API testing and example code generation

Security & Governance

  • Standardized Authentication: OAuth2, API keys, OIDC token validation

  • Policy Engine: Rate limiting, quotas, IP filtering, request/response transformation

  • Centralized Audit Trail: All API calls logged for compliance and troubleshooting

  • End to End Security: Gravitee being an API Management platform doesn’t replace the end to end encryption and zero-trust principles that must be applied to secure the communication between the consumer and the backend service.

Operational Efficiency

  • Centralized Monitoring: Real-time analytics on API usage, performance, and errors

  • Reduced Training Burden: Single platform reduces onboarding time for new developers

  • Economies of Scale: Shared infrastructure reduces per-team operational costs

  • Consistent Support Model: Unified support channel and knowledge base

Future-Proofing

  • Agent Mesh Expansion: Gravitee 4.9 supports AI agent-to-agent communication patterns

  • MCP (Model Context Protocol): APIs exposed as MCP tools for AI agent consumption

  • Event-Driven Architecture: Kafka management capabilities for async patterns

  • Cloud-Native: Kubernetes-native architecture supports containerized workloads

Evaluation of Alternatives

Option 1: Hybrid Model (Gravitee + Team Choice = Status Quo)

Pros:

  • No migration effort required

  • Teams retain full autonomy

  • No learning curve for new platform

Cons:

  • Fragmentation persists: Doesn’t solve discoverability and standardization problems

  • Poor discoverability: No centralized API catalog

  • Duplicated effort: Teams rebuild rate limiting, monitoring, documentation

  • Operational overhead: Multiple tools to maintain and support

  • Confusion: Teams unclear on when to use which platform

Verdict: Rejected - Does not address core problems and scales poorly

Option 2: MuleSoft for All APIs

Pros: - Single platform for internal and external APIs - Enterprise-grade security and compliance - Existing vendor relationship

Cons:

  • Slower time-to-market: More complex deployment process

  • Reduced developer autonomy: Centralized team bottleneck

  • Migration effort: Re-implementing existing Gravitee APIs

  • Higher cost: MuleSoft licensing and operational expenses

Verdict: Rejected - Better suited for external APIs only or complex integration implementations

📊 Performance and Scalability

Latency Overhead

Measured Impact:

  • Additional network hop introduces ~3-10ms latency per API call

  • Actual overhead varies based on policy complexity and geographic distances

Mitigation Strategies:

  • Multi-region deployment (US West, EU Germany) reduces geographic latency

  • Gateway caching for frequently accessed data

  • Connection pooling and keep-alive optimization

  • Document performance SLAs in API contracts

Scalability and Availability

Infrastructure:

  • Hosting: Minerva (EU+ US) multi-region availability

  • Architecture: Kubernetes-native, supports auto-scaling based on load

Capacity Planning:

  • Current deployment supports 400+ APIs in pRED with no performance degradation

  • Expected gRED adoption adds 100-200 APIs over 12 months, the current load with 300 APIs is 10 requests/s while the setup capacity is > 100 requests/s

Monitoring and Observability

Built-In Capabilities:

  • Real-time API analytics dashboard

  • Request/response logs with sampling

  • Error rate tracking and alerting

  • Consumer usage patterns and trends

Integration Points:

  • Export metrics to enterprise monitoring (Prometheus, Grafana)

  • Log aggregation to centralized logging platform

  • Alerting integration with PagerDuty or ServiceNow

❓ FAQ

Q: Is Gravitee mandatory for all APIs?

A: Yes this is a requirement. New APIs must use Gravitee unless there’s a documented exception (e.g., external APIs, sub-milliseconds requirements). Existing stable APIs can remain as-is.

Q: What if my API is consumed by external partners?

A: External APIs should use MuleSoft for public internet exposure. If you have an existing internal API, use Proxify to expose it externally rather than re-implementing in MuleSoft.

Q: How much latency does Gravitee add?

A: Measured overhead is ~5ms per API call, which is negligible for most RESTful APIs. Benefits like caching can actually improve performance.

Q: Who pays for the Gravitee license?

A: The license is centrally funded by CS CoE - there’s no cost to individual teams.

Q: What if I already have a custom API gateway (nginx, Envoy, etc.)?

A: You don’t need to replace it - Gravitee complements existing infrastructure rather than replacing it. Here’s how they work together:

  • Keep your existing components: Load balancers (nginx, HAProxy), service meshes (Istio), and ingress controllers remain in place

  • Gravitee adds management: It sits in front of your infrastructure, providing API catalog, authentication, rate limiting, and analytics

  • Integration pattern: Consumer → Gravitee → Your Load Balancer → Backend Services

Clarification: "Custom API gateway" typically refers to application-level proxies (nginx, Envoy) or custom-built routing layers. Gravitee is an API Management Platform that operates at L7 and provides governance, not a replacement for infrastructure components.

Q: I use AWS API Gateway or other cloud provider similar services, what should I do?

A: AWS Gateway and other similar services are used to materialize the API, usually out of lambdas and multiple other services. Gravitee is used as an API management platform on top of those services to provide a unified API catalog, authentication, rate limiting, and analytics across all APIs within CS CoE. You can continue using AWS API Gateway for your backend services while leveraging Gravitee for management.

Q: How long does onboarding take?

A: Target is <1 days for initial onboarding

Q: What happens if Gravitee has an outage?

A: Gravitee is deployed multi-region (US, EU) with 99.9% SLA. In the event of an outage, consumers cannot access your API until the gateway recovers.

Q: Can I use Gravitee for non REST APIs?

A: Gravitee support multiple protocols (REST, SOAP, gRPC) and event-driven APIs. However, RESTful APIs are the primary use case. Evaluate on a case-by-case basis.

Q: How can backend prevent direct access by passing Gravitee?

A: Multiple solutions can be used depending on your architecture:

  • Network-level restrictions: Firewall rules, security groups to only allow Gravitee IPs

  • Mutual TLS: Enforce mTLS between Gravitee and backend services

  • API Keys / Tokens / Basic auth / SEcrets: Backend validates identity issued to Gravitee

📚 Resources