How Uber Built Its Self‑Service API Gateway: Architecture & Key Lessons

In recent years, API gateways have become essential in microservice architectures, and Uber’s self‑service API gateway serves as a unified entry point for all its applications, offering routing, protocol translation, rate limiting, load shedding, header enrichment, data‑center affinity, security auditing, user access blocking, and mobile client generation.

Uber’s API gateway architecture is described in detail to help readers understand its design.

The gateway abstracts API provision as a service, supporting a range of protocols (JSON, Thrift, Protobuf) and enabling complex payload operations across multiple protocols.

API Management

Engineers configure API parameters via a UI, publishing functional APIs for Uber apps. Configuration controls paths, request/response types, rate limits, allowed apps, protocols, target microservices, headers, observability, field mapping, and validation. Once published, the gateway infrastructure materializes these configurations into functional APIs and generates client SDKs.

The UI guides users through endpoint creation, validates configurations, and allows setting timeouts, monitoring, and alerts.

Components in the Request Lifecycle

Incoming requests flow through a stack of components: protocol manager, middleware, handler, and backend client.

Protocol Manager handles deserialization/serialization for each supported protocol (JSON, Thrift, Protobuf) and can accept any payload type for the given protocol.

Middleware Layer implements cross‑cutting concerns such as authentication, authorization, and rate limiting. Multiple middleware can be attached to an endpoint; failure short‑circuits the stack.

Endpoint Handler validates requests, transforms payloads, and maps endpoint requests to backend client requests, performing response validation and serialization.

Client is protocol‑aware, sending requests to backend services with configurable features like request/response transformation, schema validation, circuit breaking, retries, timeouts, and error handling.

Configuration Components

All components are configured via YAML and Thrift files stored in a Git repository. YAML provides component metadata and acts as glue, while Thrift defines payload schemas and protocol semantics.

Protocol Manager Configuration

YAML specifies protocol type, Thrift file path, and handling methods. Example shows an HTTP API with details defined in apiSample.thrift.

Middleware Configuration

Middleware enables higher‑order features. Example adds an authentication middleware that reads header.x-user-uuid and a transformRequest middleware that maps region to regionID for backend calls.

Handler Configuration

Handlers focus on request validation and mapping to backend client parameters. If field names differ, transformRequest middleware performs the mapping.

Client Configuration

Backend client configuration combines YAML and Thrift. Example shows a TChannel‑based service defined in backendSample.thrift with two callable methods.

Deployable Artifacts

All YAML and Thrift configurations are required to describe a complete API. Uber’s gateway generates a runnable build artifact via code generation rather than dynamic configuration alone.

Code generation produces Go code for Thrift and Protobuf definitions, custom serialization for i64 and enums, and resolves a DAG of dependencies among endpoints, middleware, and clients.

The final step iterates the DAG to generate endpoint code, inject dependencies, and hydrate IDL objects.

Feature Unlocks

The gateway enables centralized features for all internal services, such as rich audit logging, reusable authentication implementations (AuthN/AuthZ), circuit breaking, fine‑grained rate limiting, automatic documentation generation, mobile client code generation, response field trimming, data‑center affinity routing, and short‑term user bans.

Challenges & Lessons Learned

Key challenges included language choice (Go and Java vs. previous Node.js), handling multiple serialization formats, managing dynamic configuration versus code‑generated artifacts, UI limitations for bulk editing, and the need to sometimes deserialize payloads for advanced features.

Overall, Uber’s self‑service API gateway demonstrates a complex yet extensible architecture that can be replicated using the open‑source Zanzibar library and an Envoy‑based runtime.