How do companies organize APIs across microservices?

Companies usually organize APIs across microservices using a mix of domain boundaries, API gateways, shared standards, and lifecycle governance. The exact setup varies, but the common goal is to make each service independently owned while still giving clients a simple, stable way to use the system.

Common ways APIs are organized

1. One API per microservice

Each microservice exposes its own API for its domain:

• orders service → order creation, cancellation, status
• payments service → charge, refund, payment status
• users service → profile, authentication, preferences

Pros

• Clear ownership
• Easy to deploy independently
• Domain boundaries stay clean

Cons

• Clients may need to call many services
• Risk of tight coupling if clients depend directly on internal service APIs

---

2. API Gateway in front of microservices

An API gateway provides a single entry point for clients and routes requests to the right microservice.

Typical responsibilities:

• Authentication/authorization
• Rate limiting
• Request routing
• Protocol translation
• Aggregation of multiple service calls

Example:

• Client calls GET /api/orders/123
• Gateway routes to orders-service
• Gateway may also fetch user info from users-service and combine responses if needed

Pros

• Simpler for clients
• Centralized cross-cutting concerns

Cons

• Can become a bottleneck if overused
• May hide service boundaries
• Can turn into a “mini monolith” if too much business logic is put there

---

3. Backend-for-Frontend (BFF)

Instead of one gateway for all clients, companies sometimes create a separate API layer for each client type:

• Web BFF
• Mobile BFF
• Partner BFF

Each BFF adapts backend microservice APIs to the needs of that specific client.

Why this helps

• Mobile apps may need fewer fields and fewer round trips
• Web apps may need richer or more complex data
• Different clients can evolve independently

---

4. Domain-driven API grouping

APIs are often grouped by business domain, not by technical layer.

For example:

• catalog
• inventory
• checkout
• billing
• identity

This aligns with bounded contexts from domain-driven design.

This helps avoid:

• Services based purely on technical concerns like “database service” or “utility service”
• Overly shared generic APIs

---

How companies keep APIs manageable

5. Consistent API standards

Even if services are independent, companies usually standardize:

• URL conventions
• HTTP methods and status codes
• error format
• pagination and filtering
• authentication mechanisms
• versioning rules
• naming conventions

Example:

• GET /orders/{id}
• POST /orders
• consistent JSON error structure across services

This makes the system feel unified to clients.

---

6. API versioning

Services evolve independently, so companies use versioning strategies such as:

• URI versioning: /v1/orders
• header-based versioning
• backward-compatible additive changes

A good practice is to avoid breaking changes and prefer:

• adding fields
• deprecating gradually
• keeping old versions alive for a period

---

7. Service contracts and schemas

Companies often define APIs using:

• OpenAPI/Swagger for REST
• gRPC/protobuf for internal service-to-service APIs
• GraphQL schemas for certain client-facing layers
• AsyncAPI for event-driven interfaces

This helps with:

• documentation
• code generation
• contract testing
• governance

---

8. Event-driven APIs

Not all API communication is synchronous. Many companies use events between microservices:

• OrderCreated
• PaymentSucceeded
• InventoryReserved

This reduces direct dependencies and helps with scalability.

Typical pattern:

• API request creates an order
• orders-service emits an event
• payments-service and inventory-service react asynchronously

---

Typical architecture pattern

A common setup looks like this:

• Clients call an API Gateway or BFF
• Gateway/BFF routes to domain microservices
• Microservices communicate:
  • synchronously for immediate needs
  • asynchronously through events for decoupled workflows
• Each service owns its own API and data

---

Organizational patterns inside companies

9. Team-owned APIs

A strong pattern is:

• one team owns one or more microservices
• the team owns the API design, docs, monitoring, and lifecycle

This reduces coordination overhead and helps teams move independently.

---

10. Platform and governance teams

Larger companies often have:

• platform teams that provide gateway tooling, auth, observability, templates
• architecture or API governance teams that enforce standards
• security teams that review exposure policies

This balances autonomy with consistency.

---

Best practices

• Keep APIs aligned to business domains
• Avoid letting clients directly depend on internal service APIs where possible
• Use gateways/BFFs to simplify client access
• Standardize error handling, auth, and versioning
• Prefer backward-compatible changes
• Document contracts and test them
• Use events for loose coupling when immediate response isn’t required

Common pitfalls

• Too many tiny services with too many APIs
• Putting business logic in the gateway
• Inconsistent API styles across teams
• No versioning or deprecation policy
• Clients depending on private internal service APIs
• Overusing synchronous calls across many services

If you want, I can also show:

1. a sample microservice API map for an e-commerce company, or
2. the difference between API gateway vs BFF vs direct service APIs.