Architecture

Enterprise API Architecture: Building Production-Ready Systems

Patterns for APIs shared across many teams: domain boundaries, contract-first design, gateways, backends for frontends, events, security and versioning.

By the APIStack team··Updated ·8 min read

The Earth at night seen from orbit, with city lights visible

An API architecture becomes an enterprise concern when many teams build services that many other teams and clients depend on. The technical problems are familiar ones; what changes is that every decision about boundaries, contracts and shared infrastructure now has to hold up across teams that deploy independently.

This article covers the decisions that matter most in that setting: where to draw service boundaries, how to agree contracts before code, what belongs in a gateway, when a backend for frontend or an event stream is the right tool, and how to handle security, versioning and operations. It is aimed at developers and architects designing or untangling a multi-team API estate.

Draw boundaries around business domains

The most consequential decision is which service owns what. Domain-driven design gives a practical rule: draw boundaries around business capabilities, each with its own vocabulary and data, which it calls bounded contexts. An online shop has a catalog, ordering, payments and customer accounts. Each has its own idea of what a "product" or a "customer" is, and each changes for different reasons.

Boundaries drawn this way tend to be stable, because business capabilities change more slowly than technology. They also line up with team ownership, which matters because a service owned by two teams ends up coordinated by meetings. Boundaries drawn around technical layers, such as a "database service" or a "validation service", do the opposite: every feature crosses all of them.

The public API should reflect the same division, with each domain exposing resources under its own path prefix.

HTTP
GET  /v1/catalog/products/8841
POST /v1/orders
GET  /v1/orders/52917
POST /v1/payments/refunds
GET  /v1/customers/me

A useful test of a boundary is whether a typical change touches one service. If most features need coordinated releases of several services, the boundaries are in the wrong place, and merging services is a legitimate fix.

Design the contract before the code

In a contract-first process the API description is written, reviewed and agreed before either side implements it. The usual format for HTTP APIs is OpenAPI. A fragment for one operation looks like this.

YAML
openapi: 3.1.0
info:
  title: Orders API
  version: 1.4.0
paths:
  /v1/orders/{orderId}:
    get:
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The order
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: No order with this ID

The steps that make the description useful, in order, are:

  1. Write the OpenAPI description for the new or changed operations.
  2. Review it with the teams that will consume it, using generated documentation or a mock server so they can try it.
  3. Check it automatically against shared rules for naming, errors and pagination with a linter such as Spectral.
  4. Implement the service and test its responses against the description in CI.

The last step is the one teams skip, and without it the description drifts from the behaviour until nobody trusts it. Consistency across services comes mostly from the third step: a shared rule set, enforced by a tool, does more than a style guide people are expected to remember.

Put shared concerns in a gateway

An API gateway is the single entry point for client traffic. It terminates TLS, routes each request to the service that owns the path, and applies the checks that should be identical everywhere: authenticating the caller, rate limiting, request size limits and access logging. Centralizing these means a service team cannot forget them, and clients see one host instead of a dozen.

The sketch below shows those responsibilities in Express using express-rate-limit, jsonwebtoken and http-proxy-middleware. It is meant to show what a gateway does, not to suggest writing one.

JavaScript
import express from 'express'
import jwt from 'jsonwebtoken'
import { rateLimit } from 'express-rate-limit'
import { createProxyMiddleware } from 'http-proxy-middleware'

const app = express()

app.use('/v1', rateLimit({ windowMs: 60_000, limit: 300, standardHeaders: 'draft-7', legacyHeaders: false }))

function authenticate(req, res, next) {
  const [scheme, token] = (req.get('authorization') || '').split(' ')
  if (scheme !== 'Bearer' || !token) {
    return res.status(401).json({ error: 'Access token required' })
  }
  try {
    req.user = jwt.verify(token, process.env.JWT_PUBLIC_KEY, {
      algorithms: ['RS256'],
      issuer: 'https://auth.example.com/',
      audience: 'https://api.example.com',
    })
    next()
  } catch {
    res.status(401).json({ error: 'Invalid or expired token' })
  }
}

const forward = (target) => createProxyMiddleware({ target, changeOrigin: true })

app.use('/v1/catalog', forward('http://catalog:3001'))
app.use('/v1/orders', authenticate, forward('http://orders:3002'))
app.use('/v1/customers', authenticate, forward('http://customers:3003'))

app.listen(8080)

An invalid token gets 401, because the caller has not been identified; 403 is for an identified caller who lacks permission. Express removes the mount path before proxying, so with http-proxy-middleware 3 the orders service receives /52917 for a request to /v1/orders/52917.

In production, use an existing gateway such as Envoy, Kong, NGINX or your cloud provider's managed service. They handle connection pooling, retries, health checks and configuration reloads that a hand-written proxy will get wrong. Note also that the rate limiter above counts in process memory, so each gateway replica keeps its own count; a real deployment needs a shared store.

Two rules keep a gateway healthy. Business logic stays out of it: once the gateway knows how to assemble an order summary, every team needs a gateway release to ship a feature. And services do not treat the gateway as their only defence. The gateway authenticates; each service still decides whether this caller may act on this particular object.

Give each client type its own backend when their needs diverge

A general-purpose API serves a web application, a mobile app and partner integrations with the same endpoints. That works until their needs pull apart. A mobile screen may need data from four services in one small response over a slow connection, while the web application wants richer payloads and makes several calls in parallel.

The backend for frontend pattern, described by Sam Newman, gives each client type a thin API of its own. The backend calls the domain services, combines and trims the results for that client, and is owned by the team that builds the client, so the two can change together.

The cost is another deployable per client type and some duplicated aggregation code. It is worth paying when client teams are regularly blocked waiting for changes to a shared API, or when the shared API is accumulating client-specific flags. With one client, or clients with near-identical needs, a single API is simpler.

Use events where services should not wait on each other

A synchronous call couples the caller to the availability and speed of the service it calls. For work the caller does not need finished before it responds, publishing an event is the better fit: the orders service records the order and publishes order.placed, and the email, analytics and fulfilment services each react in their own time. A new consumer can be added without changing the publisher, and a slow consumer does not slow down checkout.

Events bring their own obligations. They are a contract just as an HTTP response is, so their schemas need the same review and compatibility rules. Delivery is normally at-least-once, so consumers must tolerate duplicates. And the overall state becomes eventually consistent, which the user interface has to account for. The mechanics are covered in Microservices communication patterns.

Authenticate at the edge and authorize in every service

The security model that fits a multi-service estate is zero trust: a request is not trusted because it arrived from inside the network. The gateway validates the caller's token, and each service validates it again or receives a verified identity over an authenticated channel such as mutual TLS. Each service then makes its own authorization decision, since only it knows who owns the object being requested.

Scopes should be narrow and tied to domains, such as orders:read, so a token issued to a reporting tool cannot issue refunds. Access decisions are logged with the caller's identity. The details, including token validation and object-level checks, are in Advanced API security: implementing zero trust architecture.

Version deliberately and deprecate with notice

Once other teams depend on an API, any change to it is a negotiation. Most changes can be made compatibly: adding an optional request field, a new response field or a new endpoint breaks nobody, provided clients were told from the start to ignore fields they do not recognise. Removing or renaming a field, changing a type or tightening validation is a breaking change.

Reserve a new major version, such as /v2, for breaking changes and batch them so that versions are rare. When retiring an old version, publish the date, announce it in responses with the Sunset header defined in RFC 8594, and use request logs to find and contact the consumers still calling it. Comparing each proposed OpenAPI description against the published one in CI catches accidental breaking changes before they ship.

Make the system observable

With many services behind one request, a failure is rarely visible from a single log. Three things make the system diagnosable. Every request carries an ID assigned at the gateway and passed to every downstream call and log line. Every service emits the same basic metrics, namely request rate, error rate and latency, per endpoint. And distributed tracing, typically with OpenTelemetry, records the path of a request across services so that the slow or failing hop can be identified.

Agreeing these as platform standards, and providing them through shared libraries or the gateway, is far easier than retrofitting them after an incident.

Summary

  • Draw service boundaries around business capabilities with a single owning team; if most changes span several services, revisit the boundaries.
  • Agree the OpenAPI contract before implementation, lint it against shared rules and test the implementation against it.
  • Use a gateway for routing, authentication, rate limiting and logging, keep business logic out of it, and still authorize inside each service.
  • Add a backend for frontend or an event stream when a specific problem calls for it, not by default.
  • Prefer compatible changes, make breaking versions rare, and announce retirements with dates and the Sunset header.

Build with APIStack

One API key for validation, dates and holidays, web checks and reference data, over REST or as MCP tools for your AI agents. The free plan includes 1,000 calls a month.

Keep reading