API Design and Microservices for Backend Engineers (2026)

API design principles for tech-company backend teams in 2026

The senior backend engineer's API-design checklist in 2026 is a small set of non-negotiables. Every state-changing endpoint accepts an idempotency key. Every endpoint is documented in an OpenAPI 3.1 spec checked into git. Every response includes structured error codes (not just HTTP status). Every API has an explicit versioning policy and a deprecation policy. Every service-to-service call has a timeout, a retry policy with backoff and jitter, and a circuit breaker.

Beyond the checklist, the cultural pattern is contract-first design: the API spec is written and reviewed before any implementation. The spec generates server stubs, client SDKs, mock servers for frontend teams to develop against, and request/response validators for runtime enforcement. This shifts API-design conversations left, before code is written, when changes are cheap.

The protocol choice — REST, gRPC, or GraphQL — follows the use case:

• REST + OpenAPI for public APIs, partner integrations, and any surface that needs broad ecosystem support (curl, Postman, generic clients).
• gRPC for service-to-service calls inside the cluster. HTTP/2 multiplexing, protobuf binary encoding, and streaming primitives make it ~7-10x more efficient than JSON-over-HTTP for high-volume internal traffic. The cost: tooling complexity and weaker browser support.
• GraphQL for client-driven aggregation across many backend services. The classic use case: a mobile app that needs data from 5 services in a single round-trip and lets the client pick fields. The cost: query-complexity attack surface and N+1 patterns if resolvers aren't designed with DataLoader-style batching.

The wrong choice creates years of pain. A common 2026 anti-pattern: a startup builds a public REST API, adds gRPC for internal services, and then layers GraphQL on top of REST for the mobile client. The result is three protocols, three sets of tooling, three sets of error handling. Pick the smallest set that solves the actual problem.

Idempotency: the single most-cited API-design pattern

Idempotency is the property that retrying a request produces the same effect as a single request. For state-changing endpoints (POST, PATCH, DELETE), the canonical pattern is the client-supplied idempotency key: a unique string the client sends in a header (typically Idempotency-Key), and the server uses to de-duplicate retried writes.

The Stripe pattern (stripe.com/blog/idempotency) is the canonical reference and works as follows:

1. Client generates a UUID and sends it in the Idempotency-Key header.
2. Server checks if the key already exists in storage. If yes, return the cached response (status code + body) verbatim.
3. If no, process the request, store (key, request_hash, response) tuple with a 24-hour TTL, and return the response.
4. If the same key arrives with a different request body (request_hash mismatch), return 422 — the client is misusing the key.

A minimal Flask handler illustrating the pattern:

from flask import Flask, request, jsonify
import hashlib, json, redis

app = Flask(__name__)
r = redis.Redis()
TTL_SECONDS = 24 * 60 * 60  # 24h, per Stripe

@app.post("/v1/charges")
def create_charge():
    key = request.headers.get("Idempotency-Key")
    if not key:
        return jsonify(error="Idempotency-Key header required"), 400

    body_hash = hashlib.sha256(request.get_data()).hexdigest()
    cache_key = f"idem:{key}"
    cached = r.get(cache_key)

    if cached:
        stored = json.loads(cached)
        if stored["body_hash"] != body_hash:
            # Same key, different body = client bug
            return jsonify(error="Idempotency key reuse with different body"), 422
        return jsonify(stored["response"]), stored["status"]

    # Process the charge — must be transactional with the cache write
    response, status = process_charge(request.get_json())
    r.setex(cache_key, TTL_SECONDS, json.dumps({
        "body_hash": body_hash,
        "response": response,
        "status": status,
    }))
    return jsonify(response), status

What this handler gets right: required header (no silent fallback to non-idempotent behavior); body-hash check so reused keys with mismatched bodies fail loudly; 24-hour TTL matching Stripe's documented window; cached response returned verbatim with original status code.

What this handler does NOT get right (production gaps): the charge processing and the cache write are not transactional — if the process crashes between charging and writing the cache, the next retry will charge again. Stripe handles this with a write-ahead log: write the idempotency key with status='pending' before processing, then update with status='complete' and the response after. The senior+ implementation uses this pattern.

Idempotency keys are required for any endpoint that touches money, inventory, or external state. They are strongly recommended for any endpoint with side effects.

Microservice patterns: when to extract, when to consolidate

The 2026 industry consensus, reflected in Sam Newman's Building Microservices 2nd ed. (samnewman.io/books/building_microservices_2nd_edition), is that microservices are an organizational tool, not a technical default. Extract a service when one of three conditions is true:

• Team boundary (Conway's law). Two teams can't iterate independently because they share a deployment unit. Splitting the deployment unit unblocks both teams.
• Scaling profile divergence. One workload is read-heavy (10k QPS, mostly cached) and another is write-heavy (low QPS, transactional). They have incompatible scaling needs and noisy-neighbor patterns.
• Data-ownership boundary. Two domains have genuinely different data models, consistency requirements, or compliance constraints (e.g., PII vs. non-PII).

If none of these apply, the modular monolith is the right answer. Splitting prematurely buys you distributed-systems problems (partial failures, eventual consistency, distributed transactions) without the corresponding organizational benefit.

Contract-first OpenAPI is how teams coordinate across service boundaries. A canonical payments-endpoint spec snippet:

openapi: 3.1.0
info:
  title: Payments API
  version: 2026-01-15
paths:
  /v1/charges:
    post:
      summary: Create a charge
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ChargeRequest' }
      responses:
        '200': { description: Charge created }
        '422': { description: Validation error }

This spec is checked into git, reviewed in PRs, and used to generate the server stub, the client SDK, a mock server for frontend development, and request validators for runtime enforcement. When the spec changes, every consumer is notified via the SDK regeneration.

Service mesh (Envoy, Istio, Linkerd) is the modern infrastructure for microservices. The mesh moves cross-cutting concerns — mTLS, retries, circuit breakers, observability, traffic shaping — out of application code and into a sidecar proxy. The senior+ bar: you understand what the mesh provides versus what your application code still owns (idempotency, business-level validation, domain error handling).

Resilience patterns: circuit breaker, bulkhead, retry-with-backoff

Every production service-to-service call needs four things: a timeout, a retry policy with exponential backoff and jitter, a circuit breaker, and a bulkhead. None of these are optional. Their absence is how partial outages turn into full outages.

Circuit breaker (Hystrix-canonical). Netflix's Hystrix (github.com/Netflix/Hystrix/wiki) defined the canonical pattern. The breaker has three states: closed (calls pass through), open (calls fail fast without hitting the downstream), half-open (a small number of test calls determine if the downstream has recovered). The breaker opens when the failure rate exceeds a threshold (typically 50% over a 10-second rolling window). Hystrix is in maintenance mode but the pattern is implemented in every modern resilience library (Resilience4j, Polly, gobreaker).

Bulkhead. Isolate failure domains by allocating separate thread pools, connection pools, or concurrency limits per downstream. If service A is slow, calls to A queue up in A's pool; calls to B keep flowing through B's pool. Without bulkheads, a slow downstream eats all your threads and your service hangs entirely.

Retry with exponential backoff and jitter. The AWS Builders' Library (aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter) is the canonical reference. The key insight: synchronized retries from many clients create thundering herds that worsen the outage. Adding jitter (randomization) decorrelates the retries and lets the downstream recover.

A canonical Go implementation of full-jitter exponential backoff:

package retry

import (
    "context"
    "errors"
    "math"
    "math/rand"
    "time"
)

type Config struct {
    MaxAttempts int
    Base        time.Duration // initial delay, e.g. 100ms
    Cap         time.Duration // max delay, e.g. 30s
}

// Do retries fn with full-jitter exponential backoff per AWS Builders' Library.
// sleep = random_between(0, min(cap, base * 2^attempt))
func Do(ctx context.Context, cfg Config, fn func() error) error {
    var err error
    for attempt := 0; attempt < cfg.MaxAttempts; attempt++ {
        if err = fn(); err == nil {
            return nil
        }
        if !isRetryable(err) {
            return err
        }
        exp := float64(cfg.Base) * math.Pow(2, float64(attempt))
        capped := math.Min(exp, float64(cfg.Cap))
        sleep := time.Duration(rand.Int63n(int64(capped)))
        select {
        case <-time.After(sleep):
        case <-ctx.Done():
            return ctx.Err()
        }
    }
    return err
}

func isRetryable(err error) bool {
    var re interface{ Retryable() bool }
    return errors.As(err, &re) && re.Retryable()
}

What this code gets right: full jitter (random between 0 and the capped exponential delay) per the AWS Builders' Library recommendation; context cancellation respected during sleeps; bounded attempts; explicit retryable-error interface so non-retryable errors fail fast.

What this code does NOT include: a circuit breaker (should wrap this call), a per-call timeout (should be set on the underlying client), or correlation-id propagation (needed for distributed tracing). The senior+ implementation composes all four.

The AWS Builders' Library article on avoiding fallback (aws.amazon.com/builders-library/avoiding-fallback-in-distributed-systems) makes the related point: fallback logic itself is a source of complexity and bugs. Often the right behavior is to fail fast and surface the error, not to silently degrade.

Backwards-compatibility and deprecation discipline

The senior+ bar for API changes: never break existing clients without a documented deprecation timeline. Concretely:

• Additive changes only on existing versions. Add new optional fields. Add new endpoints. Never rename an existing field, never tighten a validation rule, never change a status code.
• Breaking changes require a new version. URL-versioned APIs introduce /v2/; date-versioned APIs introduce a new date. Both versions run in parallel during the migration window.
• Deprecate via the HTTP Sunset header (RFC 8594). Set Sunset: Wed, 01 Apr 2026 00:00:00 GMT on responses from deprecated endpoints. Set Deprecation: true. Document the replacement in a Link header.
• Instrument before you remove. Log every call to a deprecated endpoint with the API key or client identifier. Reach out to remaining users with concrete migration guidance before the sunset date. Pull the analytics dashboard before removing.

Stripe's API versioning case study (stripe.com/blog/api-versioning) describes a date-based scheme where each request is processed against the API version pinned to the calling account (or overridden by a Stripe-Version header). Stripe runs many versions in parallel for years, with translation layers between them. This is the gold standard but is operationally expensive; smaller teams typically use URL versioning with a 12-month deprecation window.

Observability is the other half of deprecation discipline. OpenTelemetry (opentelemetry.io/docs/concepts/observability-primer) is the modern standard for distributed tracing, metrics, and structured logs. Every API call is instrumented with a trace, every endpoint exposes RED metrics (rate, errors, duration), and every log line carries a correlation ID. Without observability, you cannot answer 'who is still calling the deprecated endpoint?' and the deprecation never finishes.