DEV Community: Bry

API Gateway Patterns: AWS vs Azure vs GCP

Bry — Tue, 18 Aug 2026 15:00:00 +0000

Key Points

AWS API Gateway comes in two flavors: HTTP API (cheaper, faster, 90% of use cases) and REST API (full feature set, higher cost). Use HTTP API unless you need REST API's request/response transformation or private integrations.
Azure API Management (APIM) is the only managed gateway with a built-in developer portal and a policy engine powerful enough to handle enterprise API governance without custom code.
GCP offers three overlapping products: API Gateway (serverless, OpenAPI-driven), Cloud Endpoints (gRPC and self-managed), and Apigee (enterprise-grade). Don't pick randomly — they are not interchangeable.
Common patterns — BFF (Backend for Frontend), API aggregation, and protocol translation — are cloud-agnostic in design but differ significantly in implementation cost across providers.
Cold starts on Lambda-backed gateways, APIM's XML policy syntax, and GCP's per-project quota model are the three gotchas that will cost you time in production.

Introduction

Picking an API gateway is a three-to-five year decision. Migrating between providers requires rewriting auth flows, rate-limiting config, and deployment pipelines — not just updating a URL. I've evaluated all three in production environments — migrating a client from AWS REST API to HTTP API, standing up APIM for an enterprise API program, and routing Cloud Run services through GCP API Gateway — and the differences that matter are rarely the ones in the marketing comparison tables. Most teams pick the gateway that matches their existing cloud provider without comparing what they're getting.

That's often the right call. But it helps to know what you're trading. AWS, Azure, and GCP have different design philosophies: AWS optimizes for serverless-native integration, Azure optimizes for enterprise API governance, and GCP gives you a choice between a lightweight managed service and a full API platform.

This article explains what each gateway does architecturally, compares them on the features that matter in production, covers the three patterns you'll implement on any of them, and flags the gotchas that each provider's documentation glosses over.

What an API Gateway Does

Before comparing providers, align on the job a gateway performs. An API gateway sits between clients and backend services and handles cross-cutting concerns so your services don't have to.

Diagram: Client traffic enters the gateway, which handles auth and routing before forwarding to backend services.

The five jobs a gateway performs:

Routing — match request paths to backend services, including path rewriting and load balancing.
Authentication and authorization — validate JWT tokens, API keys, or OAuth flows before traffic reaches your service.
Rate limiting — enforce per-client or per-route request quotas; protect backends from traffic spikes.
Request/response transformation — rewrite headers, translate between protocols (REST ↔ gRPC), strip or inject fields.
Observability — emit access logs, request metrics, and distributed traces without instrumenting each service.

Every provider covers these five jobs. How they expose them — and at what cost — is what differentiates them.

Request Flow Through a Gateway

Before choosing a provider, understand the sequence every request traverses. The auth, rate-limit, and routing steps happen in this order regardless of which gateway you use.

Diagram: Request flow through a gateway — auth and rate limiting happen before the backend ever receives the request.

AWS API Gateway

AWS offers three API products under the API Gateway brand: HTTP API, REST API, and WebSocket API. HTTP API and REST API are the ones backend engineers choose between daily.

HTTP API vs REST API

Feature	HTTP API	REST API
Price	$1.00 / million requests	$3.50 / million requests
Latency overhead	~6 ms	~11 ms
JWT authorizer (native)	Yes	No — Lambda authorizer required
Request/response transforms	No	Yes (mapping templates)
Usage plans / API keys	No	Yes
Private integrations (VPC Link)	Yes	Yes
WebSocket	No — separate product	No
AWS WAF integration	Yes	Yes

Use HTTP API for Lambda-backed services, JWT-authenticated endpoints, and any new API where you don't need request/response mapping templates. It costs 71% less than REST API and imposes half the latency overhead. I default to HTTP API for every new AWS project — the only time I've reached for REST API in the last two years was when a client needed usage plans for billing third-party API consumers.

Use REST API when you need usage plans and API keys for third-party developer access, request/response transformation via mapping templates, or Cognito user pool authorizers without a Lambda function.

Lambda Integration

The typical AWS pattern connects API Gateway directly to Lambda. The gateway acts as the event source; Lambda handles the business logic.

// AWS Lambda handler — receives API Gateway proxy event
import { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda';

export async function handler(
  event: APIGatewayProxyEventV2,
): Promise<APIGatewayProxyResultV2> {
  const userId = event.pathParameters?.userId;

  if (!userId) {
    return {
      statusCode: 400,
      headers: { 'Content-Type': 'application/problem+json' },
      body: JSON.stringify({
        type: 'https://api.example.com/errors/400',
        title: 'Bad Request',
        status: 400,
        detail: 'userId path parameter is required',
      }),
    };
  }

  // Business logic here
  return {
    statusCode: 200,
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userId, status: 'active' }),
  };
}

# HTTP API route configuration (AWS SAM / CloudFormation)
Resources:
  GetUserFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: dist/handler.handler
      Runtime: nodejs22.x
      Events:
        GetUser:
          Type: HttpApi
          Properties:
            Path: /users/{userId}
            Method: GET
            Auth:
              Authorizer: JWTAuthorizer

  MyHttpApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      Auth:
        Authorizers:
          JWTAuthorizer:
            JwtConfiguration:
              Audience: ["https://api.example.com"]
              Issuer: "https://auth.example.com/"
            IdentitySource: "$request.header.Authorization"

The Cold Start Gotcha

Lambda-backed HTTP APIs incur cold start latency when a function instance is not warm. For a Node.js 22.x Lambda with a small bundle, cold starts add 200–800 ms. For a Java or .NET Lambda with a heavy runtime, expect 1–5 seconds.

Mitigations:

Enable Provisioned Concurrency on the Lambda — eliminates cold starts for pre-warmed instances, billed hourly even when idle.
Keep Lambda bundle size under 5 MB (smaller = faster cold start).
Use SnapStart for Java Lambda functions (zero cold start after initial activation).

Cold starts do not affect AWS ECS or EKS backends connected via VPC Link — they only affect Lambda integrations. I've seen this burn teams who built their entire p99 latency budget around gateway benchmarks, then went live and got paged at 3 AM because a burst of new connections spiked p99 to 2.8 seconds — the Lambda was a .NET 6 function with a 40 MB bundle and no Provisioned Concurrency.

Azure API Management (APIM)

Azure APIM is architecturally different from AWS API Gateway. It is not a simple proxy — it is a full API management platform with three components:

Diagram: APIM's three-component architecture — the gateway, the management plane, and the developer portal are separate concerns.

The Policy Engine

APIM's differentiating feature is its XML-based policy engine. Policies apply at four scopes: global, product, API, and operation. They execute in order: inbound → backend → outbound → on-error.

<!-- APIM policy: validate JWT, rate-limit, inject backend header -->
<policies>
  <inbound>
    <base />

    <!-- Validate JWT from Authorization header -->
    <validate-jwt header-name="Authorization" failed-validation-httpcode="401"
                  failed-validation-error-message="Unauthorized">
      <openid-config url="https://auth.example.com/.well-known/openid-configuration" />
      <audiences>
        <audience>https://api.example.com</audience>
      </audiences>
    </validate-jwt>

    <!-- Rate limit: 100 calls per 60 seconds per subscription key -->
    <rate-limit-by-key calls="100" renewal-period="60"
                       counter-key="@(context.Subscription.Id)" />

    <!-- Inject caller identity into backend header -->
    <set-header name="X-User-Id" exists-action="override">
      <value>@(context.Request.Headers.GetValueOrDefault("Authorization","")
               .Replace("Bearer ",""))</value>
    </set-header>
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <!-- Strip internal headers before returning to client -->
    <set-header name="X-Internal-Trace-Id" exists-action="delete" />
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

The policy engine handles authentication, rate limiting, caching, transformation, and error handling — without custom code. For an enterprise that manages 50+ APIs across multiple teams, that centralization is the primary value proposition.

Developer Portal

APIM includes a fully customizable developer portal out of the box. Developers browse APIs, subscribe to products, generate API keys, and test endpoints — all without involving the API team. AWS and GCP's native gateways require third-party tooling (e.g., Backstage, Stoplight) to achieve the same.

Pricing Tiers

Tier	Price (approx.)	Notes
Consumption	$3.50 / million calls	Pay-per-use. No SLA for developer portal.
Developer	~$50/month	Dev/test only. No production SLA.
Basic	~$150/month	Up to 1M calls/month included.
Standard	~$750/month	Full features, 99.9% SLA.
Premium	~$3,800+/month	Multi-region, VNET integration, 99.95% SLA.

The Consumption tier looks attractive but lacks the developer portal SLA and several advanced policy features. Standard is the minimum for production workloads with enterprise requirements. In practice, I recommend clients skip Consumption entirely for anything customer-facing — the cost delta between Consumption and Standard is irrelevant next to the engineering hours you'll spend working around its limitations.

GCP: API Gateway, Cloud Endpoints, and Apigee

GCP's three API products have overlapping names and confusingly similar descriptions. Choose the wrong one and you'll hit feature walls or pay for enterprise features you don't need.

Product	Best for	OpenAPI	gRPC	Developer portal	Pricing model
API Gateway	Serverless backends (Cloud Run, Functions)	Yes (OAS v2)	No	No	Per-call
Cloud Endpoints	gRPC services, self-managed gateway	Yes	Yes	No	Per-call
Apigee	Enterprise, partner APIs, monetization	Yes	Yes	Yes	Subscription

Use API Gateway when your backend runs on Cloud Run, Cloud Functions, or App Engine and you want a fully managed gateway with no infrastructure to operate. Import your OpenAPI spec and Google provisions the gateway.

Use Cloud Endpoints when your services speak gRPC, or when you need to host the gateway proxy (ESPv2) on your own runtime for private networking. Cloud Endpoints is also the right choice for local development with gRPC tooling.

Use Apigee when you need a developer portal, API monetization, advanced bot detection, or multi-cloud/hybrid deployment. Apigee is the only GCP option that competes directly with Azure APIM.

GCP API Gateway — OpenAPI-Driven Configuration

# openapi.yaml — GCP API Gateway configuration
swagger: "2.0"
info:
  title: User Service API
  version: "1.0"
host: api.example.com
schemes:
  - https
produces:
  - application/json

x-google-backend:
  address: https://user-service-xyz-uc.a.run.app
  deadline: 30.0

securityDefinitions:
  firebase:
    authorizationUrl: ""
    flow: implicit
    type: oauth2
    x-google-issuer: "https://securetoken.google.com/my-project"
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com"
    x-google-audiences: "my-project"

paths:
  /users/{userId}:
    get:
      summary: Get user by ID
      operationId: getUser
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      security:
        - firebase: []
      responses:
        "200":
          description: User found
        "401":
          description: Unauthorized
        "404":
          description: Not found

# Deploy to GCP API Gateway
gcloud api-gateway api-configs create user-service-v1 \
  --api=user-service \
  --openapi-spec=openapi.yaml \
  --project=my-project \
  --backend-auth-service-account=api-gateway-sa@my-project.iam.gserviceaccount.com

gcloud api-gateway gateways create user-service-gateway \
  --api=user-service \
  --api-config=user-service-v1 \
  --location=us-central1 \
  --project=my-project

The GCP Quota Gotcha

GCP API Gateway enforces quotas at the project level. If you run multiple APIs or environments in the same GCP project, they share quota limits. A traffic spike on one API eats into the quota headroom for every other API in that project. I've seen this catch teams when a batch job saturated API quotas during an off-hours data migration, which cascaded into 429s on the customer-facing API living in the same project — a production incident that had nothing to do with the customer-facing service itself.

Structure your GCP projects to isolate production APIs. One project per environment (dev, staging, prod) is the minimum. One project per service in production is safer for high-traffic APIs.

Feature Comparison

Feature	AWS HTTP API	AWS REST API	Azure APIM (Standard)	GCP API Gateway	GCP Apigee
Auth: JWT	Native	Lambda authorizer	Policy (validate-jwt)	OpenAPI extension	Policy
Auth: API keys	No	Yes	Yes	Yes	Yes
Auth: OAuth 2.0	Partial (JWT)	Lambda authorizer	Policy	No	Yes
Rate limiting	Yes	Yes (usage plans)	Yes (per subscription)	Yes (per consumer)	Yes (advanced)
Request transform	No	Yes (mapping templates)	Yes (policy engine)	No	Yes
Response transform	No	Yes	Yes	No	Yes
Protocol translation	No	No	Yes (REST ↔ SOAP)	No	Yes
Developer portal	No	No	Yes (built-in)	No	Yes
gRPC support	No	No	No	Via Endpoints	Yes
WebSocket	Separate product	No	No	No	No
Multi-region active-active	No (regional)	No	Premium tier	No	Yes
Pricing model	Per-call	Per-call	Tier (monthly)	Per-call	Subscription
Cold starts	Lambda-dependent	Lambda-dependent	None	None	None

Common Patterns

Backend for Frontend (BFF)

The BFF pattern uses a dedicated gateway layer per client type — one for the web app, one for the mobile app — to avoid forcing different clients to negotiate a single general-purpose API.

Diagram: BFF pattern — each client type gets a dedicated aggregation layer tailored to its data needs.

A BFF does data aggregation and transformation — it is not where business logic lives. Business rules belong in the downstream services.

On AWS, implement each BFF as a separate Lambda function or ECS service behind its own HTTP API route. On Azure, use APIM products to route mobile vs web clients to different backends. On GCP, deploy separate Cloud Run services and separate API Gateway configurations.

API Aggregation

Aggregation collapses multiple downstream service calls into a single response for the client. The gateway (or a BFF) fans out the requests in parallel and merges the results.

// API aggregation pattern — call multiple services in parallel
import express, { Request, Response } from 'express';

const app = express();

interface OrderSummary {
  order: unknown;
  inventory: unknown;
  shipping: unknown;
}

/**
 * GET /orders/:id/summary — returns a merged view of order, inventory, and shipping data.
 *
 * @remarks
 * Fans out to three downstream services in parallel. If any service fails,
 * the endpoint returns 502 with the name of the failing service.
 *
 * @returns Merged order summary or 502 with failing service name.
 */
app.get('/orders/:id/summary', async (req: Request, res: Response) => {
  const { id } = req.params;

  const [orderRes, inventoryRes, shippingRes] = await Promise.allSettled([
    fetch(`http://order-service/orders/${id}`),
    fetch(`http://inventory-service/stock/${id}`),
    fetch(`http://shipping-service/shipments/${id}`),
  ]);

  for (const [name, result] of [
    ['order', orderRes],
    ['inventory', inventoryRes],
    ['shipping', shippingRes],
  ] as const) {
    if (result.status === 'rejected') {
      res.status(502).json({ error: `upstream_failure`, service: name });
      return;
    }
  }

  const summary: OrderSummary = {
    order: await (orderRes as PromiseFulfilledResult<Response>).value.json(),
    inventory: await (inventoryRes as PromiseFulfilledResult<Response>).value.json(),
    shipping: await (shippingRes as PromiseFulfilledResult<Response>).value.json(),
  };

  res.json(summary);
});

app.listen(3000);

Protocol Translation

Protocol translation converts between API protocols at the gateway layer. The most common case in enterprise environments is REST-to-SOAP, where a new REST API sits in front of a legacy SOAP backend.

Azure APIM handles this natively with the soap-to-rest policy. On AWS or GCP, you write a Lambda or Cloud Run adapter that performs the translation.

<!-- Azure APIM: expose a REST endpoint backed by a SOAP service -->
<policies>
  <inbound>
    <base />
    <!-- Convert REST JSON body to SOAP XML envelope -->
    <set-body>
      @{
        var body = context.Request.Body.As<JObject>();
        return string.Format(
          @"<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/'
                              xmlns:usr='http://legacy.example.com/user'>
              <soapenv:Body>
                <usr:GetUser>
                  <usr:UserId>{0}</usr:UserId>
                </usr:GetUser>
              </soapenv:Body>
            </soapenv:Envelope>",
          body["userId"]
        );
      }
    </set-body>
    <set-header name="Content-Type" exists-action="override">
      <value>text/xml; charset=utf-8</value>
    </set-header>
    <set-header name="SOAPAction" exists-action="override">
      <value>http://legacy.example.com/user/GetUser</value>
    </set-header>
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <!-- Parse SOAP response and return JSON -->
    <xml-to-json kind="direct" apply="always" consider-accept-header="false" />
  </outbound>
</policies>

Protocol translation is one of the strongest arguments for Azure APIM. Implementing the same pattern on AWS requires a Lambda adapter and custom XML parsing logic. If your organization has legacy SOAP services that need a REST facade, I would pick Azure APIM over any other provider specifically for this — the AWS alternative is a Lambda that becomes a maintenance liability the moment the original SOAP developer leaves.

API Lifecycle Management

Every gateway manages API versions moving through environments. The state diagram below represents the lifecycle that applies regardless of provider.

Diagram: API lifecycle from development through retirement. Breaking changes are only safe before the API reaches Production.

On AWS, implement environment promotion by deploying to separate API Gateway stages (dev, staging, prod). On Azure, use APIM's revision system for non-breaking changes and a new API version for breaking changes. On GCP API Gateway, deploy to separate gateway instances per environment.

Choosing the Right Gateway

Diagram: Decision flowchart for selecting a gateway.

Common Mistakes

Mistake 1: Using AWS REST API when HTTP API covers your needs
REST API costs 3.5× more per million requests and adds ~5 ms of latency over HTTP API. The only reasons to choose REST API over HTTP API are mapping templates for request/response transformation, usage plans with API keys, or Cognito user pool authorizers. If none of those apply, HTTP API is the correct choice.

Mistake 2: Ignoring Lambda cold starts in latency budgets
Teams measure gateway latency and see 6 ms. They assume their API responds in under 100 ms. Then they deploy to production and discover p99 latency is 700 ms because the Lambda behind the gateway cold-starts on every new burst. Cold starts are not a gateway problem — they are a Lambda problem — but they manifest as gateway latency and are often debugged at the wrong layer.

Mistake 3: Choosing Azure APIM Consumption for production without reading the tier limitations
The Consumption tier has no SLA for the developer portal, limits on policy features, and no built-in cache. Teams select it for cost reasons and hit limitations mid-project. Standard is the correct production tier for most workloads.

Mistake 4: Mixing multiple APIs in a single GCP project
GCP API Gateway enforces quotas at the project level. Multiple APIs in one project share quota. A traffic spike on one API reduces the available quota for all others in the same project. Separate projects per environment (and per service in production for high-traffic APIs) is the safe default.

Mistake 5: Building complex API aggregation in gateway mapping templates
AWS REST API mapping templates (Velocity Template Language) and Azure APIM policies can both perform data transformation. Use them for simple field renaming or header injection. Do not use them to aggregate multiple backend calls, implement business logic, or transform complex nested structures — that complexity belongs in a BFF service where it is testable and maintainable.

Production Considerations

Performance

AWS HTTP API adds ~6 ms of median gateway overhead. REST API adds ~11 ms. Set your latency budget accordingly.
Azure APIM Standard tier median overhead is 5–15 ms depending on policy complexity. A policy chain with JWT validation, rate limiting, and transformation adds up.
GCP API Gateway overhead is 5–20 ms. Apigee overhead is higher due to the full policy engine.

Security

On AWS, attach a WAF WebACL to your HTTP API or REST API. The gateway itself validates JWT signatures but does not inspect payloads for SQL injection or XSS patterns.
On Azure APIM, use the ip-filter policy to block known-bad IP ranges and the validate-content policy for schema validation. APIM integrates with Azure DDoS Protection at the Premium tier.
On GCP, pair API Gateway with Cloud Armor for DDoS protection and request filtering. Apigee has built-in bot detection and threat protection.

Cost

AWS HTTP API at 1 billion requests/month: ~$1,000. Lambda execution costs are separate.
Azure APIM Standard: ~$750/month flat plus overage. Standard includes 1M calls/month; additional calls are $3.50/million.
GCP API Gateway at 1 billion requests/month: ~$2,000 (calls over the free tier at $3.00/million above 2M).

Monitoring

On AWS, enable CloudWatch detailed metrics for your API Gateway and set alarms on 4XXError, 5XXError, Latency, and IntegrationLatency. IntegrationLatency isolates backend latency from gateway latency — critical for cold start diagnosis.
On Azure, use APIM's built-in Application Insights integration. Track Backend Duration separately from Gateway Duration to identify whether slowness is in the gateway policies or the backend.
On GCP, Cloud Logging and Cloud Trace integrate automatically. Set a budget alert on API call costs in the GCP Console — GCP quotas can run up quickly on traffic spikes.

Full Example: API Aggregation Service (TypeScript)

This aggregation service sits behind an API Gateway (on any provider) and fans out to three downstream services in parallel. It returns a merged response or reports which upstream failed.

import express, { Request, Response, NextFunction } from 'express';
import { randomUUID } from 'crypto';

const app = express();
app.use(express.json());

// ─── Types ───────────────────────────────────────────────────────────────────

/** Represents the shape of a downstream service response for an order. */
interface OrderData {
  id: string;
  status: string;
  total: number;
  lineItems: Array<{ productId: string; qty: number }>;
}

/** Inventory availability per product. */
interface InventoryData {
  productId: string;
  available: number;
  reserved: number;
}

/** Shipment tracking details. */
interface ShipmentData {
  trackingNumber: string;
  carrier: string;
  estimatedDelivery: string;
  status: string;
}

/** Merged summary returned to the client. */
interface OrderSummaryResponse {
  requestId: string;
  order: OrderData;
  inventory: InventoryData[];
  shipment: ShipmentData | null;
}

/** RFC 7807 problem detail shape for error responses. */
interface ProblemDetail {
  type: string;
  title: string;
  status: number;
  detail: string;
  instance?: string;
}

// ─── Helpers ─────────────────────────────────────────────────────────────────

function problem(
  res: Response,
  status: number,
  title: string,
  detail: string,
  instance?: string,
): void {
  const body: ProblemDetail = {
    type: `https://api.example.com/errors/${status}`,
    title,
    status,
    detail,
    ...(instance ? { instance } : {}),
  };
  res.status(status).contentType('application/problem+json').json(body);
}

/**
 * Fetch a downstream service and parse the JSON response.
 *
 * @remarks Throws with a structured error if the upstream returns non-2xx.
 * Caller is responsible for catching via Promise.allSettled.
 *
 * @param url - Full URL of the downstream service endpoint.
 * @returns Parsed JSON response body.
 * @throws {Error} when upstream returns a non-2xx status.
 */
async function fetchUpstream<T>(url: string): Promise<T> {
  const res = await fetch(url, {
    headers: { 'X-Request-Id': randomUUID() },
    signal: AbortSignal.timeout(5000), // 5 s timeout per upstream call
  });

  if (!res.ok) {
    throw new Error(`Upstream ${url} returned ${res.status}`);
  }

  return res.json() as Promise<T>;
}

// ─── Routes ──────────────────────────────────────────────────────────────────

/**
 * GET /orders/:id/summary — fan-out aggregation across order, inventory, and shipping services.
 *
 * @remarks
 * **Path parameters:**
 * - `id` — Order UUID. Must exist in the order service.
 *
 * **Responses:**
 * - `200 OK` — All three upstreams responded successfully.
 * - `404 Not Found` — Order service returned 404.
 * - `502 Bad Gateway` — One or more upstreams failed or timed out; body identifies which.
 */
app.get('/orders/:id/summary', async (req: Request, res: Response) => {
  const { id } = req.params;
  const requestId = randomUUID();

  const ORDER_SVC = process.env.ORDER_SERVICE_URL ?? 'http://order-service';
  const INV_SVC = process.env.INVENTORY_SERVICE_URL ?? 'http://inventory-service';
  const SHIP_SVC = process.env.SHIPPING_SERVICE_URL ?? 'http://shipping-service';

  const [orderResult, shipmentResult] = await Promise.allSettled([
    fetchUpstream<OrderData>(`${ORDER_SVC}/orders/${id}`),
    fetchUpstream<ShipmentData>(`${SHIP_SVC}/shipments/${id}`),
  ]);

  if (orderResult.status === 'rejected') {
    problem(res, 502, 'Upstream Failure', `Order service failed: ${orderResult.reason}`, req.path);
    return;
  }

  const order = orderResult.value;

  // Fetch inventory for each line item in parallel
  const inventoryResults = await Promise.allSettled(
    order.lineItems.map(item =>
      fetchUpstream<InventoryData>(`${INV_SVC}/stock/${item.productId}`),
    ),
  );

  const inventoryFailure = inventoryResults.find(r => r.status === 'rejected');
  if (inventoryFailure) {
    problem(res, 502, 'Upstream Failure', 'Inventory service failed for one or more products', req.path);
    return;
  }

  const summary: OrderSummaryResponse = {
    requestId,
    order,
    inventory: inventoryResults.map(r => (r as PromiseFulfilledResult<InventoryData>).value),
    shipment: shipmentResult.status === 'fulfilled' ? shipmentResult.value : null,
  };

  res.json(summary);
});

// ─── Error handler ───────────────────────────────────────────────────────────

app.use((err: Error, req: Request, res: Response, _next: NextFunction) => {
  console.error('Unhandled error', { path: req.path, error: err.message });
  problem(res, 500, 'Internal Server Error', 'An unexpected error occurred.', req.path);
});

// ─── Start ───────────────────────────────────────────────────────────────────

const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;
app.listen(PORT, () => {
  console.log(`Aggregation service running on port ${PORT}`);
});

Run the service:

npm install
ORDER_SERVICE_URL=http://localhost:3001 \
INVENTORY_SERVICE_URL=http://localhost:3002 \
SHIPPING_SERVICE_URL=http://localhost:3003 \
npm run dev

Test the aggregation endpoint:

# Aggregated response from three services in one call
curl -s http://localhost:3000/orders/order-abc123/summary | jq

# Expected shape:
# {
#   "requestId": "uuid",
#   "order": { "id": "order-abc123", "status": "confirmed", ... },
#   "inventory": [{ "productId": "...", "available": 10 }, ...],
#   "shipment": { "trackingNumber": "...", "status": "in_transit" }
# }

Full source with tests: GitHub link → cloud-apis/api-gateway-patterns/

Conclusion

AWS HTTP API is the right default for Lambda-backed services — it is faster and costs less than REST API, and covers 90% of use cases. Azure APIM wins when your organization needs a developer portal, enterprise API governance, or REST-to-SOAP translation without custom code. GCP's three options serve different tiers: API Gateway for serverless, Cloud Endpoints for gRPC, and Apigee for enterprise. The BFF pattern, API aggregation, and protocol translation are cloud-agnostic in concept but differ significantly in implementation cost — Azure APIM handles protocol translation natively, while AWS and GCP require adapter services. The decision you should walk away from this article having made: stop treating gateway selection as a checkbox in your cloud provider's onboarding wizard. The wrong choice costs you months of workarounds; the right one disappears into your infrastructure and you stop thinking about it entirely — which is exactly what a good gateway should do.

Story Points After AI: When Velocity Metrics Stop Meaning What They Used To

Bry — Wed, 12 Aug 2026 15:00:00 +0000

Key Points

Story points and velocity were built on an assumption: that the effort to draft a solution roughly tracked the effort to deliver it. AI is breaking that link by collapsing drafting effort toward zero while leaving verification effort largely where it was.
A team whose velocity jumps from 50 to 5,000 in a sprint hasn't gotten 100x better. It's produced a number that no longer measures the thing anyone cares about, and more engineering leaders are quietly admitting this every quarter.
What's replacing velocity isn't a single metric. It's a shift toward outcome-oriented measures: defect density in AI-generated code, rework percentage, lead time to value, and issue resolution time, none of which can be inflated just by generating more draft code faster.
Why the Man-Month Is Dying: How AI Broke IT Services' Oldest Pricing Unit covered why the man-month is dying as a pricing unit. This one covers the parallel death of story points as a delivery-measurement unit. The two are breaking for the same underlying reason, on different sides of the same contract.

Introduction

A client-side engineering director told me recently that her team's velocity chart looked like a hockey stick after they rolled out agentic coding tools, and that she'd stopped showing it to her own leadership because it made her look like either a liar or an idiot. Neither was true. Her team had actually improved. The chart just couldn't say by how much, or at what, because the number it produced no longer meant what it used to mean.

Story points measure estimated effort, and velocity is story points delivered per sprint, a proxy that worked reasonably well as long as the bottleneck in software delivery was drafting: writing the code, wiring up the boilerplate, working through the mechanical parts of a ticket. AI-assisted development attacks exactly that bottleneck and leaves the other one, verification, largely untouched. When drafting effort collapses toward zero and verification effort doesn't move much, a velocity number built on the old ratio between the two stops correlating with anything real. Scrum.org's own framing of the problem is blunt: if a team's velocity jumps from 50 to 5,000 in a single sprint, they haven't gotten 100x better. They've broken the metric, because it was always a proxy for effort, and AI reduces the drafting effort to near-zero while leaving verification complexity high.

The industry data backs up how fast this is becoming unignorable. Teams running agentic AI tools report 10-20x velocity gains alongside 40-78% fewer bugs, numbers that sound like unambiguous good news until you try to use them for the same planning and comparison purposes velocity was always used for. You cannot forecast a roadmap, compare two teams, or set a hiring plan against a metric that swings by two orders of magnitude depending on which AI tool got rolled out last quarter. Teams that haven't found a replacement are flying blind with better instruments than they've ever had, which is its own kind of dangerous.

Old Velocity Metrics vs. Post-AI Delivery Metrics

Criteria	Story Points / Velocity	Post-AI Delivery Metrics
What it actually measures	Estimated drafting effort per sprint	Defect density, rework rate, lead time to value, issue resolution time
Inflatable by AI tooling alone	Yes, trivially, without any real gain	No, each metric requires an actual outcome to move
Useful for cross-team comparison	Only if both teams use identical tooling and estimation habits	Yes, outcomes are tooling-agnostic
Useful for client-facing reporting	Increasingly not, since AI adoption accelerated in 2026	Yes, clients can verify a defect rate or a resolution time against their own experience
What a spike in the number tells you	Nothing reliable	That verification-adjusted output actually improved

Recommendation: if your organization is still running sprint retros around a velocity chart, check whether anyone on the team can explain what a 10x jump in that number would actually mean. If the honest answer is "the tooling changed," the metric isn't tracking delivery anymore. It's tracking tool adoption, and you should be measuring that separately from outcome quality.

Where This Is Likely Headed

Right now: denial and dashboards for most teams. Most teams are keeping the velocity chart because the tooling to replace it (defect-density tracking, rework attribution, lead-time-to-value instrumentation) isn't built yet, and nobody wants to be first to admit their headline metric is cosmetic.
Expect a credibility break within the next year or two. As more teams get publicly embarrassed by an unexplainable 50-to-5,000 velocity swing, engineering leadership will stop defending the metric in front of executives and clients. "Agent efficiency" language is already starting to replace "velocity" in serious planning conversations.
Outcome metrics should go from experimental to standard within a few years. Rework percentage and AI-attributed defect rate are becoming normal line items on engineering dashboards, not because they're perfect, but because they can't be gamed by pointing an agent at a backlog overnight.
The end state: metrics become a client-facing artifact, not just an internal one. Firms moving toward outcome-based contracts are starting to share rework and defect data directly with clients, because the metric is finally honest enough to survive that exposure.

Questions to Ask Your Team

If our velocity doubled next sprint, could anyone on this team explain exactly why, in terms a client would find credible?
Are we tracking rework and defect rate on AI-generated code specifically, or lumping it in with everything else and losing the signal?
Would we be comfortable sharing our current delivery metrics directly with a client, or are they really an internal-only number dressed up as evidence of progress?
Is any part of a team's evaluation or bonus still tied to raw velocity, in a way that quietly rewards inflating a number everyone privately agrees is broken?

Conclusion

Story points and velocity aren't failing because someone calculated them wrong. They're failing because the thing they measured, effort, is no longer correlating with the thing everyone actually wanted to know, which was progress. The teams adapting fastest aren't the ones with the flashiest AI tooling. They're the ones willing to admit their dashboard is lying to them and replace it with metrics, defect density, rework rate, lead time to value, that can't be inflated by the same tools that broke the old ones. The man-month is dying on the pricing side of the contract. Velocity is dying on the delivery side. Neither death is really about AI being too good. It's about a proxy finally getting exposed as a proxy.

AWS EventBridge: Event Buses and Rules You Can Script from Day One

Bry — Tue, 11 Aug 2026 15:00:00 +0000

Key Points

EventBridge charges $1.00 per million custom events published; rule evaluation itself is free, up to 300 rules per bus. The real billing surprise isn't rule count — it's payload size, since events bill in 64 KB chunks and the January 2026 limit increase to 1 MB means one large event can now bill as up to 16.
A custom event bus, a rule with a JSON event pattern, and a Lambda target take four CLI commands total. Use InputTransformer on targets to trim events down to only the fields a target needs, rather than forwarding the full body downstream.
Archive and replay are cheap to enable and expensive to forget about — archived data bills monthly storage whether or not you ever replay it.

Prerequisites

CLI/SDK version tested against: aws-cli/2.35.x
An IAM role with events:* and lambda:InvokeFunction permissions
A deployed Lambda function to act as a target — the examples use order-processor

Introduction

EventBridge gets pitched as "SNS but smarter" often enough that people underrate how little code it takes to get real value from it. I've stood up event-driven order processing for two different clients using nothing but a custom bus, a handful of pattern-matched rules, and existing Lambda functions — no message broker to run, no queue infrastructure to patch.

The part that doesn't show up in the marketing is the cost mechanic that changed in January 2026: AWS raised the maximum event payload from 256 KB to 1 MB, which sounds like a pure win until you notice events still bill in 64 KB chunks. A single 1 MB event can now bill as 16 separate chunked events at the custom-event rate. That's not a reason to avoid EventBridge — it's a reason to design your event payloads deliberately instead of dumping an entire domain object into detail.

This article builds a working bus, rule, and target from the terminal, and treats the payload mechanic as a design input, not an afterthought.

Bus, Rules, Targets: The Three Pieces

Diagram: one bus, multiple rules each matching a different event pattern, each routing to its own target.

A rule without a target does nothing but sit there for free. A rule with a matching event pattern and a wired-up target is what actually moves data. Rules and targets are separate API calls on purpose — one rule can fan out to up to five targets.

Building It From the CLI

# 1. A custom bus — separate from the default bus so your rules
#    only ever see events your own services publish.
aws events create-event-bus --name orders-bus

# 2. A rule matching a specific event pattern on that bus.
aws events put-rule \
  --name order-created-rule \
  --event-bus-name orders-bus \
  --event-pattern '{
    "source": ["orders-service"],
    "detail-type": ["OrderCreated"],
    "detail": {
      "status": ["pending"]
    }
  }'

# 3. Grant the rule permission to invoke the Lambda target.
aws lambda add-permission \
  --function-name order-processor \
  --statement-id eventbridge-invoke \
  --action lambda:InvokeFunction \
  --principal events.amazonaws.com \
  --source-arn "arn:aws:events:us-east-1:123456789012:rule/orders-bus/order-created-rule"

# 4. Wire the rule to the Lambda target.
aws events put-targets \
  --rule order-created-rule \
  --event-bus-name orders-bus \
  --targets '[{
    "Id": "order-processor-target",
    "Arn": "arn:aws:lambda:us-east-1:123456789012:function:order-processor"
  }]'

Four commands, and the bus is live. Publish a test event to confirm the wiring:

aws events put-events --entries '[{
  "Source": "orders-service",
  "DetailType": "OrderCreated",
  "Detail": "{\"orderId\":\"order-abc123\",\"status\":\"pending\",\"total\":49.99}",
  "EventBusName": "orders-bus"
}]'

A successful response returns "FailedEntryCount": 0. If it's 1, check Errors in the same response — the two most common causes are a malformed Detail JSON string or a detail-type/source combination that doesn't match any rule, which fails silently rather than erroring (the event is simply dropped with no matching rule, and EventBridge does not treat that as a failure).

Designing Around the Payload-Chunking Rule

Diagram: EventBridge's per-64KB chunking mechanic, effective with the January 2026 payload limit increase to 1 MB.

The fix isn't "never send large events." It's "don't send more than the target needs." Two concrete patterns:

Send a reference, not the full object. If order-created-rule's target only needs the order ID to go fetch full details itself, publish {"orderId": "order-abc123"} in detail, not the entire order document with line items, customer data, and shipping addresses.

Use InputTransformer to trim before delivery. When the target genuinely needs specific fields from a larger event, extract them at the rule level instead of forwarding everything:

aws events put-targets \
  --rule order-created-rule \
  --event-bus-name orders-bus \
  --targets '[{
    "Id": "order-processor-target",
    "Arn": "arn:aws:lambda:us-east-1:123456789012:function:order-processor",
    "InputTransformer": {
      "InputPathsMap": {
        "orderId": "$.detail.orderId",
        "status": "$.detail.status"
      },
      "InputTemplate": "{\"orderId\": <orderId>, \"status\": <status>}"
    }
  }]'

InputTransformer runs on EventBridge's side before delivery — it doesn't reduce what you're billed for publishing the original event, but it does mean your Lambda isn't parsing (and your logs aren't storing) a payload larger than it needs.

Archive and Replay

Archiving lets you replay events later — useful for reprocessing after a bug fix, or reconstructing state after a downstream outage. It's cheap per operation and easy to forget about entirely.

aws events create-archive \
  --archive-name orders-archive \
  --event-source-arn arn:aws:events:us-east-1:123456789012:event-bus/orders-bus \
  --retention-days 30

Component	Price
Archive processing	$0.10/GB archived
Archive storage	$0.023/GB-month
Replayed events	$1.00/million (same as custom event rate)

Storage bills every month an archive exists, whether or not anything ever gets replayed from it. Set --retention-days deliberately — 30 days is a reasonable default for operational replay; longer retention should be a conscious compliance or audit decision, not the default you forgot to change.

Common Mistakes

Mistake 1: Publishing to the default bus for everything
The default bus receives AWS service events too. Mixing your application events into it makes rule patterns harder to write precisely and makes the bus noisier to reason about. Use a custom bus per domain area.

Mistake 2: Assuming a failed match throws an error
It doesn't. An event with no matching rule is dropped silently — put-events still returns success. Test your event patterns against real sample events before relying on them in production.

Mistake 3: Forwarding entire event payloads to every target
This is both a cost issue (larger payloads, more chunked billing on any downstream re-publish) and a coupling issue — targets that receive more than they need tend to accumulate implicit dependencies on fields nobody documented.

Mistake 4: Enabling archive without a retention policy decision
Storage costs accrue every month regardless of replay activity. An archive with no retention limit and no owner is exactly the kind of AWS bill line item nobody can explain six months later.

Production Considerations

Performance: Rule matching is fast and free regardless of rule count up to the 300-per-bus limit. If you're approaching that limit, it's usually a sign you need multiple buses segmented by domain, not one bus straining to model everything.

Security: Use resource-based policies on the event bus (put-permission) to control which accounts or services can publish, rather than relying solely on IAM policies at the producer side.

Cost: Re-run the payload math whenever a producer's event shape grows. A field added "just in case" on a high-volume event source compounds fast at the chunked billing rate.

Monitoring: CloudWatch metrics on TriggeredRules, FailedInvocations, and ThrottledRules are free and on by default — set an alarm on FailedInvocations per target, since a misconfigured target fails silently from the publisher's perspective.

Full Example: Teardown Script

#!/usr/bin/env bash
set -euo pipefail

BUS_NAME="${BUS_NAME:-orders-bus}"
RULE_NAME="${RULE_NAME:-order-created-rule}"

aws events remove-targets --rule "$RULE_NAME" --event-bus-name "$BUS_NAME" --ids order-processor-target
aws events delete-rule --name "$RULE_NAME" --event-bus-name "$BUS_NAME"
aws events delete-archive --archive-name orders-archive || true
aws events delete-event-bus --name "$BUS_NAME"

echo "Torn down $BUS_NAME and its rules."

Full source including the sample Lambda target and pattern-matching tests: GitHub → cloud-apis/aws-eventbridge-cli/

Conclusion

EventBridge is one of the fastest AWS services to script from zero — a working bus, rule, and target is four commands. The part worth designing around deliberately is payload size: with the 2026 increase to a 1 MB event limit, it's easy to publish something large enough to bill as multiple events without noticing. Send references and trim payloads with InputTransformer rather than forwarding full objects downstream, and treat archive retention as a decision you make on purpose, not a default you forgot existed.

Why the Man-Month Is Dying: How AI Broke IT Services' Oldest Pricing Unit

Bry — Wed, 05 Aug 2026 15:00:00 +0000

Key Points

The man-month (one person, one month of billable effort, priced roughly the same regardless of what actually got produced) was the pricing atom of IT services for over several decades ago. By 2026 it's a legacy unit, still written into a shrinking pool of contracts nobody has gotten around to renegotiating.
The break point is dateable. In February 2026, Fujitsu publicly attributed a modification job that would have taken three man-months to four hours of AI-assisted work, and formally announced a shift "from the conventional man-month base to a customer-provided value base." NTT Data and INSEAD's joint research that April reached the same conclusion from the outside: the man-month model's sustainability was no longer assumed. It was in question.
This opens an eight-part thread on what replaced the man-month across systems integration: pricing, subcontracting, staffing, delivery practice. It starts here, with the unit itself and why it broke.
What replaced it isn't one model. Outcome-based fees, asset/subscription hybrids, and old-fashioned time-and-materials all still exist, but they're chosen deliberately now, not defaulted to because nobody bothered to price the actual result.
The firms that struggled hardest weren't the ones using AI badly. They were the ones whose entire commercial structure, quotas, career ladders, partner compensation, was load-bearing on selling hours, with nothing else to sell once hours stopped being the scarce resource.

Introduction

I sat through a renegotiation meeting in late 2026 where a client's procurement lead asked our account team, flatly: "You're telling me this now takes a quarter of the time it used to. Why does the invoice look the same?" Nobody in the room had a good answer. The honest one, "our pricing model was never actually about the work, it was about the hours we could bill for it," isn't something you say out loud to a client who just found that out for themselves.

That meeting was a preview of what happened to the entire industry over the years to come. The man-month, the unit IT services has priced against since the mainframe era, assumed labor was the scarce, expensive input and that more of it reliably meant more delivered value. AI-assisted development broke that assumption specifically, not generally. It didn't make engineers better at everything. It made the drafting and implementation portion of the work cheap enough that billing by the hour spent on it started to look less like a pricing model and more like an admission that nobody had measured what the client actually received.

Fujitsu's February 2026 disclosure is the cleanest marker of when this became undeniable inside the industry rather than just argued about outside it: a modification job estimated at three man-months got done in four hours with AI assistance, and the company followed with an official policy statement moving away from man-month pricing toward pricing tied to customer value. NTT Data didn't wait to be embarrassed by a competitor's number. Its joint research with INSEAD two months later stated directly that AI adoption was affecting "the sustainability of the traditional man-month model," and recommended outcome-oriented or asset-utilization pricing instead. Two of Japan's largest systems integrators, independently, arrived at the same read within a single quarter.

Man-Month Billing vs. What Replaced It

Criteria	Man-Month Billing	Outcome / Asset-Based Billing
What the client pays for	Time occupied by a person, regardless of output	A defined result, a usage tier, or an asset the vendor built once and licenses
Vendor incentive under AI acceleration	Perverse: faster delivery shrinks the invoice	Aligned: faster delivery keeps the same fee and improves margin
Client's ability to verify value received	Weak. Trusts the vendor's time reporting	Strong. Result is specified and checkable before payment
Effect of a 10x AI productivity gain	Revenue collapses unless hours are padded	Revenue holds; the gain becomes margin, not a threat
What a firm needs to sell it	Headcount utilization	A track record, a defined asset, or a measurable outcome definition

Recommendation: if your organization is still quoting new work by estimated person-months in 2033, that's not a pricing choice anymore. It's a sign nobody has built the measurement infrastructure (defined outcomes, reusable assets, usage metering) that every other model in this table requires. That infrastructure is the actual work of the transition, not the invoice template.

How the Transition is Expected to Unfolded, 2026 onwards

2026: acknowledgment, not action. Fujitsu and NTT Data said the model was breaking. Almost nobody had a replacement ready. Outcome-based contracts existed in theory (IDC was already projecting 30% of IT services contracts would be outcome-based by 2029), but most firms kept quoting man-months out of habit and contract-template inertia.
The bifurcation. Firms split into two groups. One group treated AI purely as a cost lever: same man-month invoices, fewer people doing the work, margin absorbed internally as long as clients didn't notice. The other group renegotiated openly, moved toward hybrid subscription-plus-usage or defined-outcome pricing, and used the freed-up delivery capacity to take on more client relationships instead of padding timesheets.
Forecasts beaten, not missed. IDC's Forecast that the 30%-outcome-based-by-2029 number that looked aggressive in 2026 may turn out to be conservative. Clients who'd seen one vendor bill honestly for AI-accelerated work stopped tolerating man-month invoices from everyone else.
Consolidation around the honest group. The firms still running pure headcount-utilization economics didn't disappear overnight, but their new-business win rate kept sliding against competitors who could show a client exactly what they were paying for and why the price made sense at AI-native delivery speed.

Questions to Ask Your Team

If we quoted this job today the way we would have in 2025, by estimated person-months, would the number even make sense against how fast we can actually deliver it now?
Do we have a defined, checkable outcome for our top five client engagements, or are we still trusting time reports as the only measure of value delivered?
When AI cuts delivery time on a piece of work, does that show up as margin for us or as an automatic discount we're not charging for?
Is any part of our compensation or promotion structure still built around billable-hour targets that actively punish a team for delivering faster?

Conclusion

The man-month didn't die because AI made engineers obsolete. It died because it was always a proxy, for effort, for scarcity, for how much of a scarce input a client needed to buy, and AI broke the proxy's connection to the thing it was supposed to measure. Fujitsu and NTT Data said so publicly in 2026 because the gap had gotten too large to paper over. What comes next in this thread is the part that actually took years to work out: what replaced story points as a proxy for progress, how subcontracting economics reshuffled under the same pressure, and what a systems integrator actually sells once headcount stops being the product.

API Gateway for Business Leaders: What It Is, Why It Matters, and How to Adopt It

Bry — Tue, 04 Aug 2026 15:00:00 +0000

Key Points

An API gateway is the single front door through which all digital traffic enters your software systems — like a hotel concierge that handles every request before routing it to the right department.
Without one, every client application talks directly to every backend service — a security nightmare that gets worse as you scale.
The core business payoff: one place to enforce security, one place to see all traffic, and the freedom to change your backend without disrupting your customers.
Main costs are driven by API call volume and data transfer — budget $50–$500/month for small to mid-size deployments on managed cloud providers.
Adopt if you run more than three backend services and serve more than one client application; skip it if you have a single small app with one consumer.

Introduction

Your engineering team has built ten microservices over three years. Each one has its own authentication logic. None of them share a logging format. When a security vulnerability hits one, your team scrambles to patch ten places. When a new mobile app wants to access any of them, integration takes weeks per service.

This is the API sprawl problem — and it gets worse every time your business adds a new product, partner integration, or user-facing application. The API management market reached $8.9 billion in 2024 and is growing at over 17% annually, driven by organizations recognizing that managing APIs at scale without a central control layer is unsustainable.

An API gateway is that control layer. I've seen this exact problem in organizations that had six engineers, then twenty, then sixty — and the teams that centralized their API infrastructure early were the ones that didn't spend half their fourth year firefighting integration debt. This article explains what it does, what it costs, who should adopt it, and how to evaluate whether your organization is ready.

What Is an API Gateway?

Think of an API gateway as the customs checkpoint at an international airport. Every passenger — every request from a mobile app, partner system, or internal tool — passes through a single checkpoint before reaching their destination. The checkpoint verifies identity, checks what you are allowed to carry through, routes you to the right terminal, and logs your passage. None of the individual terminals need to run their own security lines.

Without a gateway, your software looks like an airport where every gate runs its own customs procedure. Passengers (requests) arrive at any door they can find. Each gate hires its own security staff. The records are fragmented. When a threat emerges, there is no single place to shut it down.

In technical terms: an API gateway is a reverse proxy that sits between your clients and your backend services, handling authentication, routing, rate limiting, monitoring, and protocol translation centrally.

The problem it solves: as organizations add services, the number of direct connections between clients and services grows exponentially. Five services serving four client types means up to twenty separate integration points to secure, monitor, and maintain — each one a potential vulnerability and a maintenance burden.

Before and After

Before: nine direct connections, each requiring its own security, logging, and maintenance. After: three connections to one gateway — which manages everything downstream.

Key Benefits

Benefit	What It Means in Practice	Who Gains
Centralized security	Authentication and access control enforced once, at the gateway — not duplicated across every service	Security team, compliance officers
Full traffic visibility	Every API call is logged in one place — who called what, when, how often, whether it succeeded	Engineering, product, finance
Backend flexibility	Change or replace a backend service without touching client applications	Engineering team, product velocity
Rate limiting and abuse prevention	Automatically throttle runaway traffic before it reaches your systems	Operations, infrastructure cost
Faster partner integrations	New partners connect once to the gateway, not to each individual service	Business development, sales
Cost predictability	Caching at the gateway reduces redundant backend calls and cloud compute costs	Finance, engineering

With Gateway vs Without Gateway

Criteria	Without API Gateway	With API Gateway
Security surface	Distributed — each service is an independent attack target	Centralized — one hardened entry point
Time to add a new client	Weeks — each service must be integrated separately	Days — connect once to the gateway
Incident response time	Slow — must patch auth or logging in multiple services	Fast — single change propagates everywhere
Traffic visibility	Fragmented — each service logs differently or not at all	Unified — consistent logs, dashboards, alerts
Ability to scale teams independently	Low — teams depend on each other's service interfaces	High — gateway contract isolates frontend and backend teams
Operational cost at scale	High — duplicated effort across every service	Lower — shared infrastructure amortized across all services
Vendor / tech migration risk	High — clients are tightly coupled to backend implementation	Low — swap backend services without client changes

Bottom line: for organizations running more than three backend services or serving more than one client type, an API gateway pays for itself in reduced integration and security overhead within the first year.

How It Works (Without the Code)

The gateway operates as a single front door. When a request arrives — say, a mobile app asking for a customer's order history — the gateway performs several steps before any backend service ever sees the request.

First, it verifies identity. Is the caller who they claim to be? This is authentication. The gateway checks a credential (a token, an API key) so that no individual service needs to implement its own login logic.

Second, it checks permissions. Is this caller allowed to access this resource? A partner integration might access order data but not payment details. The gateway enforces this boundary.

Third, it routes the request to the right service. The caller addresses the gateway at one address; the gateway knows where each internal service lives and forwards accordingly.

Fourth, it records everything. Who called, what they asked for, how long it took, whether it succeeded. This audit trail feeds dashboards, billing systems, and security alerts.

The response follows the same path in reverse. The backend service answers the gateway; the gateway returns the answer to the caller. From the caller's perspective, there is one system. Behind the gateway, there can be dozens.

Cloud Provider Options

All three major cloud providers offer managed API gateway services. Choosing between them is primarily a question of where your existing infrastructure lives — not a question of technical superiority.

Provider	Product	Best Fit	Pricing Model
AWS	Amazon API Gateway	Organizations already on AWS (Lambda, EC2, ECS)	Per million API calls — HTTP APIs from $1.00/million, REST APIs from $3.50/million
Azure	Azure API Management (APIM)	Organizations on Microsoft Azure or using Microsoft 365, Active Directory	Tiered monthly plans — Developer tier from ~$50/month, Production tiers from ~$285/month
Google Cloud	GCP API Gateway / Apigee	Organizations on Google Cloud or requiring advanced analytics and monetization	Per call pricing for API Gateway; Apigee uses capacity-based enterprise contracts

How to choose: start with the cloud you already use. Switching cloud providers to get a different API gateway is never worth it — the gateway features across all three are comparable for standard use cases. If you are not yet committed to a cloud, I recommend AWS — the ecosystem integration, documentation depth, and available talent pool are hard to beat for most organizations. If you require enterprise-grade analytics, developer portals, and API monetization, Apigee (Google's enterprise offering) leads the market — Gartner named it a leader in the 2025 Magic Quadrant for API Management, and in practice it is the only realistic choice when API monetization is a business requirement rather than a nice-to-have.

Pros and Cons

Advantages

Single security enforcement point: Patch a vulnerability or change an authentication policy in one place rather than across every service simultaneously.
Operational leverage: One engineering team can manage gateway policies that protect dozens of backend services — a force multiplier on your security and platform teams.
Faster product iteration: Backend teams change their services without coordinating with every client team. The gateway contract stays stable while implementations evolve.
Measurable traffic data: First time many organizations have a clear view of who uses their APIs, at what volume, and with what error rates — information that directly informs pricing, capacity planning, and product decisions.

Disadvantages and Risks

Added infrastructure cost: A managed gateway adds a recurring cloud bill. For low-traffic applications, this cost may exceed the operational savings.
Single point of failure if misconfigured: Centralizing all traffic through one layer means a gateway outage affects all services simultaneously. I've seen this play out when a team deployed a self-hosted Kong instance without HA configuration — a single bad config push took down every client-facing service for forty minutes during business hours, something that would have been impossible in the pre-gateway architecture where each service failed independently. Mitigation: use managed cloud offerings with built-in redundancy, not self-hosted solutions, unless you have a dedicated platform team.
Latency addition: Every request passes through one more network hop. The overhead is typically 1–5 milliseconds — negligible for most applications, but worth knowing if you are building latency-sensitive real-time systems.
Vendor dependency: Choosing a cloud-native gateway creates some lock-in to that provider's configuration model. Open-source alternatives (Kong, Traefik) reduce lock-in at the cost of more operational complexity. For most organizations below 200 engineers, I'd take the managed vendor lock-in — the operational burden of running your own gateway infrastructure is not a trade worth making until you have a dedicated platform team to absorb it.

Is an API Gateway Right for You?

Adopt if:

You run three or more backend services
You serve multiple client types (mobile, web, partner APIs, internal tools)
Security, compliance, or audit logging is a business requirement
Your engineering team spends time duplicating authentication or monitoring logic across services

Wait if:

Your team has fewer than five engineers and you are still validating product-market fit
You have one client and one backend — the overhead is not justified

Avoid if:

You have a single, simple application with one consumer and no plans to expand
Your API is internal-only with no external partners or clients

Adoption Roadmap

A realistic four-phase approach for an organization starting from zero.

Phase 1: Evaluate (Weeks 1–2)

Audit how many backend services you currently run and how many distinct clients access them.
Identify the single most painful integration point — the one your engineering team mentions most often in planning meetings.
Assign one technical owner and one business sponsor.
Define success criteria before starting: reduced incident response time, reduced time to onboard a new partner, or cost reduction in a specific area.

Phase 2: Pilot (Weeks 3–6)

Implement the gateway for one non-critical service — not your core payment or authentication system. In practice, a reporting API or a read-only catalog endpoint is the right first target: low blast radius if something goes wrong, real enough traffic to surface configuration issues.
Route one client type through the gateway only.
Measure against your success criteria weekly. Track gateway latency overhead, incidents, and team time spent on configuration.
Decision point at end of week six: continue, adjust, or stop.

Phase 3: Expand (Months 2–4)

Apply lessons from the pilot to your highest-priority services.
Build an internal runbook: how to add a new service, how to add a new client, how to change an access policy.
Train additional team members on gateway administration.
Review actual costs against initial estimates — cloud bills often surprise at this stage.

Phase 4: Standardize (Month 4 onward)

Establish organizational standards: every new service goes through the gateway from day one.
Set up automated cost alerts at 80% and 100% of monthly budget.
Integrate gateway access logs into your security incident response process.
Review and rotate API credentials on a defined schedule.

Cost Considerations

Cost Type	What to Budget For	Typical Range
API call volume	Primary usage charge — per million requests processed	$1–$3.50 per million (AWS); varies by provider
Data transfer	Outbound data charged separately by cloud provider	$0.09/GB (AWS); similar on Azure and GCP
Caching	Optional: reduces backend load, adds a fixed hourly cost	$20–$80/month for a dedicated cache layer
Managed tier subscription	Azure APIM and enterprise tiers charge monthly flat fees	$50–$2,000+/month depending on tier
Engineering setup time	One-time implementation cost	2–6 weeks of one engineer's time
Ongoing operations	Configuration updates, policy changes, incident response	10–20% of initial setup effort per year

ROI signal: if your engineering team spends more than two days per month resolving authentication or integration issues across multiple services, the operational savings from a centralized gateway typically offset its cost within the first six months. The teams I've worked with consistently underestimate this — they track the gateway's monthly cloud bill but not the engineering hours it replaces. Run the actual calculation before your budget discussion: hourly engineering cost times recurring integration hours is almost always the bigger number.

For a startup or small team processing under 10 million API calls per month, expect $50–$200/month on a managed cloud gateway. Mid-size organizations at 100–500 million monthly calls should budget $500–$3,000/month, depending on caching and data transfer.

Questions to Ask Your Engineering Team

Before committing, get clear answers to these:

"How many backend services do we currently run, and how many will we add in the next twelve months?"
"Where are we today duplicating authentication, logging, or rate-limiting logic across services?"
"What is our current security incident response time when a vulnerability affects an API?"
"Which cloud provider do we already use, and does their gateway offering cover our requirements?"
"Who will own gateway configuration — is this a full-time concern or a part-time responsibility?"
"What is our monthly API call volume today, and what does it look like in two years at our projected growth?"
"What does the failure mode look like if the gateway goes down? Do we have a fallback plan?"

Conclusion

An API gateway is not a technology bet — it is an operational decision about how much complexity you are willing to distribute across your engineering organization. Every organization past the startup stage is running this complexity somewhere; the question is whether it is centralized and manageable or scattered across ten services and invisible. The organizations that centralize it earlier move faster, respond to incidents faster, and spend less time on the plumbing that enables their actual product. If you take one thing from this article: the cost of the gateway is visible on your cloud bill; the cost of not having one is buried in engineering hours, incident postmortems, and integration timelines that nobody is tracking. Evaluate it now, before the complexity makes the decision for you.

Azure API Management: When Policies Beat a Hand-Rolled Gateway

Bry — Tue, 28 Jul 2026 15:00:00 +0000

Key Points

Azure API Management (APIM) is worth the setup cost the moment you'd otherwise write custom gateway code for auth, rate limiting, or protocol translation — its policy engine replaces that code with declarative XML.
The Azure CLI's az apim command group covers instances, APIs, operations, products, and version sets — but has no command for setting a policy document, a real gap in the CLI module. The workaround is az rest against the ARM REST API directly, exactly what Azure's own CLI maintainers point to when asked.
Non-Consumption APIM tiers take up to 40 minutes to provision. Plan your CI pipeline and your patience around that, not around how fast az apim create returns.
Consumption tier looks free-tier attractive but has no SLA on the developer portal — treat Standard or Standard v2 as the real production floor.

Prerequisites

CLI/SDK version tested against: az-cli 2.6x.x (Azure CLI's apim extension ships in-box on current 2.6x releases — run az version to confirm)
An Azure subscription with Microsoft.ApiManagement resource provider registered (az provider register --namespace Microsoft.ApiManagement)
A backend HTTP service to import — the examples below use a placeholder https://backend.example.com

Introduction

Most gateway comparisons put Azure APIM next to AWS API Gateway and Kong and stop at a feature checklist. That's the wrong first question. The right one is: are you about to write custom code to do something a policy engine already does declaratively? If the answer is yes — rate limiting per subscription key, JWT validation before the request reaches your backend, REST-to-SOAP translation for a legacy service — APIM's policy engine is doing real work for you, not just adding a hop.

I've stood up APIM for an enterprise client that needed exactly this: fifty internal APIs, one gateway, centrally enforced auth and rate limiting without touching a single backend service's code. The CLI got most of the way there cleanly. Then I hit the one thing nobody warns you about: there's no az apim policy set command. It doesn't exist. You'll go looking for it, because every other resource in APIM has an obvious CLI verb, and this one just... doesn't.

This article builds a real APIM instance end to end from the terminal — instance, API import, and a working policy document — and shows you the actual workaround for the missing piece.

What APIM Actually Is

APIM is not a thin proxy. It's three components that happen to share one Azure resource:

Diagram: the gateway, the management plane, and the developer portal are three separable concerns inside one APIM instance.

The policy engine is the part that actually replaces custom code. Policies are XML documents that run in a defined order — inbound, backend, outbound, on-error — and attach at four scopes: global, product, API, or a single operation. A five-line policy can do what would otherwise be a Lambda-equivalent function on AWS or a custom middleware layer anywhere else.

Standing Up the Instance

az group create --name rg-apim-demo --location eastus

# Non-Consumption tiers take up to 40 minutes to provision.
# Consumption tier (sku-name Consumption) provisions in under 5.
az apim create \
  --name apim-demo-001 \
  --resource-group rg-apim-demo \
  --publisher-email platform-team@example.com \
  --publisher-name "Example Platform Team" \
  --sku-name Developer \
  --no-wait

--no-wait matters here. If you're scripting this in CI, don't block the pipeline on a 40-minute provision — poll with az apim wait --created on a separate step, or trigger the API import as a follow-up job once provisioning completes.

az apim wait --created \
  --name apim-demo-001 \
  --resource-group rg-apim-demo \
  --timeout 3000

Importing an API

az apim api import \
  --resource-group rg-apim-demo \
  --service-name apim-demo-001 \
  --api-id orders-api \
  --path orders \
  --display-name "Orders API" \
  --service-url https://backend.example.com \
  --specification-format OpenApi \
  --specification-url https://backend.example.com/openapi.json \
  --subscription-required true

This gets you a routable API in front of your backend, with subscription-key enforcement on by default. What it doesn't get you is anything from the policy engine — no rate limiting, no JWT validation, no header rewriting. For that, keep reading.

The Policy Gap — and the Workaround

Every other APIM resource has a matching az apim verb: az apim api create, az apim product create, az apim api operation create. Look for the policy equivalent and you won't find one — az apim api's subcommand list covers create/update/delete/export/import/operation/release/revision/schema/versionset, and stops there. No policy.

Diagram: decision path once you hit the policy gap in the CLI.

The documented-nowhere-obvious answer, confirmed by Azure CLI maintainers on the azure-cli GitHub repo when the same question was raised: call the ARM REST API directly with az rest.

# Write the policy document to a file first.
cat > policy.xml << 'EOF'
<policies>
  <inbound>
    <base />
    <rate-limit-by-key calls="100" renewal-period="60"
                        counter-key="@(context.Subscription.Id)" />
    <set-header name="X-Forwarded-By" exists-action="override">
      <value>apim-demo-001</value>
    </set-header>
  </inbound>
  <backend><base /></backend>
  <outbound><base /></outbound>
  <on-error><base /></on-error>
</policies>
EOF

# Wrap the XML in the JSON body the ARM policy resource expects.
POLICY_XML=$(cat policy.xml | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')

az rest --method put \
  --uri "https://management.azure.com/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/rg-apim-demo/providers/Microsoft.ApiManagement/service/apim-demo-001/apis/orders-api/policies/policy?api-version=2022-08-01" \
  --body "{\"properties\":{\"format\":\"xml\",\"value\":${POLICY_XML}}}"

That single az rest call does what a Set-AzApiManagementPolicy PowerShell cmdlet or a portal paste into the policy editor would otherwise do — and it's the only way to keep a policy deployment in a bash-based CI pipeline without shelling out to PowerShell Core as a second runtime dependency.

Verify it landed:

az rest --method get \
  --uri "https://management.azure.com/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/rg-apim-demo/providers/Microsoft.ApiManagement/service/apim-demo-001/apis/orders-api/policies/policy?api-version=2022-08-01" \
  --query 'properties.value' --output tsv

Tier Comparison

Tier	Approx. price	SLA	Notes
Consumption	Pay-per-call, 1M free/month	No SLA on developer portal	Fastest to provision (minutes), but skip it for anything customer-facing
Developer	~$50/month	None — dev/test only	Use for exactly what the name says
Basic	~$150/month	Yes, limited scale	Entry production tier
Standard	~$700/month	Yes, full policy engine	Practical production floor for most teams
Standard v2	Comparable to Standard	Yes	Adds network-isolated backend support without Premium's full VNET cost
Premium	~$2,700+/month per unit	99.95%, multi-region	Multi-region active-active, VNET injection, availability zones

I default clients to Standard or Standard v2 for production. Consumption's lack of a developer-portal SLA and reduced policy feature set makes it a poor fit the moment external partners depend on your API catalog being reliably browsable — which is the entire point of having a developer portal in the first place.

Common Mistakes

Mistake 1: Assuming az apim is a complete CLI surface
It covers structural resources well. It does not cover policies. Budget time to discover and use az rest before you're blocked on a deploy.

Mistake 2: Blocking a CI pipeline on az apim create without --no-wait
Non-Consumption tiers take up to 40 minutes. A pipeline step with a default timeout will fail long before provisioning completes if you don't split create and wait into separate steps.

Mistake 3: Choosing Consumption tier for a customer-facing API catalog
The missing developer-portal SLA isn't a rounding-error limitation — if your onboarding flow depends on partners self-serving through the portal, an unreliable portal is a support-ticket generator.

Mistake 4: Writing policy XML by hand in the portal and never committing it to source control
The az rest path above works precisely because it turns policy deployment into something you can put in a repo and a pipeline. Portal-only policy edits are invisible to code review and impossible to diff.

Production Considerations

Performance: Policy chain complexity adds latency — a chain with JWT validation, rate limiting, and header manipulation adds measurably more than a single rate-limit-by-key policy alone. Profile with Application Insights before assuming the policy engine is "free."

Security: Pair APIM with Azure AD (Entra ID) for OAuth flows rather than rolling your own JWT validation policy from scratch — validate-jwt with an openid-config reference is less code to maintain than a custom Lambda-equivalent would be on another cloud.

Cost: The gap between Consumption and Standard is real money, but the gap between under-provisioning Standard and needing Premium's VNET injection for compliance is bigger. Confirm your network isolation requirements before committing to a tier.

Monitoring: Enable Application Insights integration at creation time, not after. Track Backend Duration separately from Gateway Duration — this is how you tell whether a slow response is APIM's policy chain or the backend service itself.

Full Example: Policy Deployment Script

#!/usr/bin/env bash
set -euo pipefail

RG="${RG:-rg-apim-demo}"
SERVICE="${SERVICE:-apim-demo-001}"
API_ID="${API_ID:-orders-api}"
SUBSCRIPTION_ID=$(az account show --query id --output tsv)

deploy_policy() {
  local policy_file="$1"
  local policy_xml
  policy_xml=$(python3 -c "import json,sys; print(json.dumps(open('$policy_file').read()))")

  az rest --method put \
    --uri "https://management.azure.com/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RG}/providers/Microsoft.ApiManagement/service/${SERVICE}/apis/${API_ID}/policies/policy?api-version=2022-08-01" \
    --body "{\"properties\":{\"format\":\"xml\",\"value\":${policy_xml}}}"

  echo "Deployed policy from $policy_file to $API_ID"
}

deploy_policy "policy.xml"

Full source with a matching teardown script: GitHub → cloud-apis/azure-api-management-policies/

Conclusion

APIM earns its keep the moment its policy engine replaces code you'd otherwise write and maintain yourself — auth validation, rate limiting, protocol translation. Standard or Standard v2 is the right production tier for nearly everyone; Consumption's missing portal SLA makes it a false economy for anything customer-facing. And when the CLI's az apim command group leaves you stuck on policies specifically, that's not a sign you did something wrong — it's a real, if quietly undocumented, gap that az rest closes in one call.

Japan Market Entry for Cloud & SaaS Vendors: What Localization Actually Requires Beyond Translation

Bry — Thu, 23 Jul 2026 15:00:00 +0000

Key Points

Translation is table stakes, not the differentiator — Japanese enterprise buyers evaluate data residency, ISMAP-equivalent security posture, and support-hour coverage before they evaluate your feature list.
Japan's information density norms invert Western UX defaults: a dashboard that reads as "clean" to a US buyer reads as sparse and untrustworthy to a Japanese one.
Data residency has moved from a nice-to-have to a procurement gate in the last few enterprise cycles — "we can serve requests from a US region" is now a disqualifying answer, not a caveat.
The RFP-to-contract cycle runs longer than most Western go-to-market plans budget for, and rushing it reads as a lack of commitment, not efficiency.

Introduction

I've watched foreign SaaS vendors run the same playbook entering Japan: hire a translation agency, localize the marketing site, hire a country manager, and expect the pipeline to behave like it did in the UK or Germany. Six months later the pipeline is full of "interested, evaluating" deals that never close, and nobody on the team can explain why the product that won in three other markets is stalling in this one.

The answer is rarely the product. It's that Japan's enterprise buying process evaluates a different set of signals than most Western markets do, and localization done as a translation exercise never touches any of them. This is the first article I am writing about this topic drawing on my own experience as a Tokyo-based engineer navigating both sides of this: implementing systems Japanese enterprises buy, and helping foreign teams understand why their otherwise-solid pitch isn't landing.

This covers what "localization" actually needs to include for a cloud or SaaS product to clear a Japanese enterprise buying committee, not just a Japanese user's browser.

What Localization Actually Means Here

Most vendors treat localization as a translation project: strings into Japanese, maybe a JP-language support inbox, done. Think of it instead like localizing a car for a market that drives on the other side of the road — you don't just relabel the pedals, you move the steering wheel, and if you skip that step the car is unsellable regardless of how good the engine is.

The problem it solves: a translated-only product fails at the point where a Japanese buyer's procurement, legal, and security teams start asking questions your localization checklist never anticipated — where is the data stored, what's your incident notification SLA under Japanese law, does your interface actually match how a Japanese team works, not just what language it displays in.

Three categories do the actual work, and translation is only one of them:

Product and UX localization — beyond string translation, into information density, workflow assumptions, and support-channel expectations.
Regulatory and security posture — APPI compliance, data residency, and (for anything touching government or large-enterprise procurement) ISMAP alignment.
Commercial and contractual localization — yen-denominated pricing, dual-language contracts under Japanese governing law, and a sales process built for a longer, more consensus-driven buying cycle.

Product Localization: Deeper Than Strings

Japanese enterprise software users expect information-dense interfaces. Where a US-market dashboard leans toward whitespace and a handful of headline metrics, the Japanese-market equivalent that wins in comparison testing tends to expose more fields, more status detail, and more explicit labeling — the same design instinct that produces Japan's famously dense transit maps and product packaging. A UI a US design team calls "clean" often reads to a Japanese buyer as incomplete, or worse, as a product that's hiding something.

Documentation carries more procurement weight here too. Japanese enterprise buyers lean on manuals, in-product help, and tooltips more heavily than a comparable Western buyer evaluating the same product, and a help center that's obviously auto-translated (mixed terminology, awkward phrasing, missing sections) reads as a signal the vendor isn't serious about the market — not a minor rough edge. Any interface where English strings leak through mid-flow (an error message that didn't get localized, a settings page half in English) gets flagged the same way a broken link gets flagged in a security review: evidence the product wasn't built with this market in mind.

Support-hour coverage matters concretely, not symbolically: JST business-hours support, staffed by people who can actually read the ticket without a translation round-trip, is close to a hard requirement for anything positioned above small-business self-serve.

Regulatory Posture: APPI, Data Residency, and ISMAP

This section is a map of what to expect, not a substitute for Japanese counsel — treat the specifics below as the shape of the requirements, and get a licensed opinion before you commit language to a contract.

APPI (Act on the Protection of Personal Information) is Japan's core data protection law, enforced by the Personal Information Protection Commission (PPC). A qualifying breach requires an initial report to the PPC within a matter of days and a detailed follow-up report within roughly two months — timelines tight enough that "we'll figure out our breach process if it happens" isn't a credible answer in a security questionnaire.

Data residency has hardened from a differentiator into a procurement gate over the last several enterprise cycles. "Our infrastructure is multi-region and includes APAC" used to be an acceptable hedge. For enterprise-tier deals today, "can you guarantee this customer's data never leaves Japan" is frequently a yes/no gate a "we're flexible" answer fails outright — not a point to negotiate after the technical evaluation.

ISMAP (Information system Security Management and Assessment Program) is the Japanese government's cloud security assessment framework, run jointly by the Cabinet Secretariat's National center of Incident readiness and Strategy for Cybersecurity and the Information-technology Promotion Agency. You don't need ISMAP registration to sell to private enterprise — it's formally a government-procurement requirement — but its control baseline has become a reference point large private-sector security teams cite in vendor questionnaires anyway, the same way SOC 2 became a de facto private-sector bar in the US despite starting as an audit standard for service organizations. ISMAP-LIU, a lighter-weight track introduced for lower-risk SaaS, is worth knowing about specifically because it's a materially smaller lift than the full framework and fits a large share of horizontal SaaS products.

Commercial Localization: Contracts, Pricing, and the Buying Cycle

Yen-denominated pricing isn't optional past the pilot stage — a USD invoice reads as "this vendor hasn't actually committed to this market" to a procurement team weighing that signal alongside your competitors' localized contracts.

Contracts should exist in Japanese and English side by side, not Japanese-only or English-only, with Japanese governing law stated explicitly. Dual-language isn't redundancy: it gives the Japanese legal reviewer a document they can actually mark up and gives your own counsel a version they can actually defend, and misalignment between the two versions is a real risk worth a proper legal translation pass, not a machine-translation shortcut.

Enterprise purchase approval in Japan typically routes through several sequential sign-offs — section chief, department head, executive director — each a real decision point, not a formality to route around. That's structurally why the cycle runs longer than the Western sales motion most foreign teams plan their quarter around, and why a vendor pushing for a faster close reads as impatient rather than efficient. The takeaway is that your localization timeline and your sales-cycle timeline need to be planned together, not sequentially — starting the sales conversation before the product, docs, and contract templates are actually ready burns the first-impression credibility you don't get to spend twice with the same buyer.

Comparison: Translation-Only vs Localized Launch vs Full Market-Entry Program

Criteria	Translation-Only	Localized Launch	Full Market-Entry Program
What's included	UI strings + marketing site in Japanese	+ UX redesign, JST support, dual-language contracts, yen pricing	+ local entity, ISMAP/ISMAP-LIU pursuit, dedicated JP sales team
Time to first enterprise contract	Rarely closes above SMB tier	6–12 months	12–24 months
Cost	Low (translation agency fees)	Moderate (design + support + legal)	High (entity setup, compliance program, headcount)
Enterprise procurement pass rate	Low — stalls at security/data-residency questions	Moderate — clears mid-market, struggles at large-enterprise/government tier	High — built to clear the tier it's targeting
Best for	Testing product-market signal cheaply before committing	Mid-market and SMB-enterprise SaaS	Enterprise and government-adjacent sales motions

Bottom line: treat translation-only as a signal-gathering step, not a market-entry strategy — use it to validate interest, then budget for the localized-launch tier before your first real enterprise sales cycle, and reserve the full program for when a specific large-enterprise or public-sector deal justifies the entity and compliance investment.

Pros and Cons

Advantages of Entering Properly

Durable relationships: Japanese enterprise buyers who complete a first contract with a vendor that respected the process tend to expand slowly but reliably — churn among properly-onboarded enterprise accounts is low relative to Western SaaS norms.
Referenceable wins compound: a single credible enterprise logo in Japan opens doors with peer companies in the same keiretsu or industry association faster than the equivalent reference does in a more fragmented Western market.
Less competitive crowding at the top tier: many foreign vendors give up at the translation-only stage, so the localized and full-program tiers have real, addressable whitespace.

Disadvantages and Risks

Sunk cost before revenue: a full market-entry program is a real capital commitment before the first enterprise contract closes — don't start it speculatively.
APPI and data-residency misses are expensive to unwind: an architecture built assuming cross-region flexibility is a real re-platforming project to fix later, not a config change.
A rushed first impression is hard to recover from: unlike markets where a bad first pitch just costs you that one deal, a vendor seen as underprepared in Japan's tighter B2B community can carry that reputation into the next three conversations.

Is This Right for You?

Enter now if:

You have inbound interest or a named target account already asking about Japan availability.
Your architecture can commit to Japan-only data residency without a rebuild.
Leadership is prepared to plan around a longer sales cycle, not shorten it.

Wait if:

You have no specific signal yet — test with a localized-launch tier aimed at mid-market before committing to full program cost.
Your product's data architecture assumes cross-region flexibility you're not ready to change.

Skip for now if:

Your total addressable market in Japan is speculative and no other APAC or domestic priority is a stronger use of the same budget this year.

Implementation Approach

Phase 1: Validate Signal (Months 1–2)

Localize marketing materials and a demo environment into Japanese — translation tier, deliberately minimal spend.
Identify 3–5 named target accounts or work existing inbound interest.
Run discovery calls with a bilingual team member present, not a translation tool.

Phase 2: Localized Launch (Months 3–8)

Commission a real UX localization pass — information density, workflow assumptions, not just string translation.
Stand up JST-hours support with staff who read tickets natively.
Draft dual-language contract templates with Japanese governing law, reviewed by Japan-qualified counsel.
Set yen-denominated pricing.

Phase 3: Compliance and Entity (Months 9–18, if pursuing enterprise/government tier)

Confirm data residency architecture — Japan-region hosting for Japan customer data, verified, not assumed.
Begin APPI compliance program formally.
Evaluate ISMAP or ISMAP-LIU registration against your specific buyer segment.
Decide entity structure — this is a legal and tax decision, not just a go-to-market one.

Phase 4: Scale (Month 18+)

Use the first 1–2 enterprise wins as referenceable case studies within the same industry vertical.
Reassess whether Japan is the right next APAC market or whether Singapore/Australia sequencing fits your specific product better.

Cost Considerations

Cost Type	What to Budget For	Typical Range
Translation-only tier	Agency translation, marketing site localization	$15,000–$40,000 one-time
UX localization pass	Redesign for information density, workflow fit	$50,000–$150,000 one-time
JST support staffing	1–2 bilingual support hires or an outsourced JP support desk	$80,000–$180,000/year
Legal and contracts	Japan-qualified counsel for dual-language contracts, APPI review	$20,000–$60,000 one-time, plus ongoing retainer
Entity and compliance program	Local entity setup, ISMAP/ISMAP-LIU pursuit if pursuing enterprise/gov	$100,000–$400,000+ over 12–18 months

ROI signal: if your average enterprise contract value in existing markets exceeds $50,000/year and you already have inbound Japan interest, the localized-launch tier typically pays back within the first two to three enterprise contracts — the full program only pays back if you're targeting large-enterprise or government accounts specifically, not general market presence.

Questions to Ask Your Team

"Can our data architecture guarantee Japan-only residency today, or is that a re-platforming project?"
"Who owns the Japanese-language version of our contract, and has Japan-qualified counsel actually reviewed it?"
"Is our support team staffed for JST business hours with people who read Japanese natively, or are we planning to route through translation?"
"Have we budgeted the sales cycle at 12+ months, or are we still modeling it on our US/EU cycle length?"
"Is this a translation-only signal test, or are we committing to the localized tier — and does everyone on the team agree which one we're doing?"

Conclusion

Translation gets a foreign SaaS product into a Japanese browser. It doesn't get it past a security questionnaire, a procurement committee, or the sales cycle those groups run on. Treat localization as three separate investments (product/UX, regulatory posture, and commercial/contractual) and size the investment to the tier of buyer you're actually targeting, not to what felt sufficient in your last market. The vendors who stall in Japan usually aren't building a worse product; they're budgeting a translation-only effort against an enterprise-tier buying process.

Getting Started with the Claude API: Messages, Streaming, and Tool Use

Bry — Tue, 21 Jul 2026 15:00:00 +0000

Key Points

Install anthropic, set ANTHROPIC_API_KEY, and you have a working LLM API in five lines of Python.
Three models cover 95% of use cases: Opus for complex reasoning, Sonnet for most production tasks, Haiku for cheap high-volume classification.
Always stream long-form responses; timeouts and bad UX come from blocking on a full response.
Tool use requires a two-turn round trip: Claude signals a function call, your code runs it, you return the result. A single turn can request several tool calls at once — extracting only the first silently drops the rest.
Prompt caching cuts input token costs by up to 90% for apps that send the same system prompt on every request.

Introduction

Most tutorials for LLM APIs stop at "send a message, print a response." That gets you a demo. It does not get you a production application. I've integrated the Claude API into customer-facing applications and internal automation pipelines, and the same three gaps appear every time a team goes from prototype to production: they don't stream, they don't handle tool use as a round trip, and they only think about cost after the first billing cycle. The Claude API has specific patterns for streaming, tool use, and cost control that are non-obvious from a basic example — and getting them wrong results in timeouts, doubled costs, or silent logic errors when Claude tries to call a function and your code ignores it.

This article covers the full picture: how the Messages API works, how to pick the right model, how to stream correctly, how to implement tool use as a complete round trip, and how to keep costs predictable at scale. All code is Python 3.11+. The companion code at ai-integration/claude-api-quickstart/src/main.py is a runnable ClaudeClient class that demonstrates all four patterns.

Setup

Install the SDK and dependencies:

pip install anthropic python-dotenv

Store your API key as an environment variable — never hardcode it:

# .env
ANTHROPIC_API_KEY=sk-ant-...

The Anthropic SDK reads ANTHROPIC_API_KEY automatically. Initialize the client once at module level:

import os
from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv()
client = Anthropic()  # reads ANTHROPIC_API_KEY from env

Create the client once. A common mistake is instantiating Anthropic() inside a request handler. The client maintains an HTTP connection pool — recreating it on every call wastes ~50ms in connection setup and adds unnecessary overhead.

Messages API Basics

Every interaction with Claude goes through client.messages.create(). The API uses three message roles:

system — sets the context and rules for the entire conversation. Not a message in the history.
user — input from the human (or your application).
assistant — Claude's previous responses. Include these to continue a multi-turn conversation.

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You are a senior backend engineer. Be concise and direct.",
    messages=[
        {"role": "user", "content": "What is the difference between process and thread?"}
    ]
)

print(response.content[0].text)
print(f"Tokens used — input: {response.usage.input_tokens}, output: {response.usage.output_tokens}")

Key parameters:

Parameter	Type	Notes
`model`	string	Required. See model selection section below.
`max_tokens`	int	Required. Upper bound on output — Claude stops here even mid-sentence.
`system`	string	Optional. Sets assistant persona and rules.
`messages`	list	Required. Alternating user/assistant turns. Must start with `user`.
`temperature`	float	0.0–1.0. Default 1.0. Lower = more deterministic. Use 0.0 for classification.
`stop_sequences`	list	Claude stops generating at any of these strings.

The response stop_reason tells you why Claude stopped:

end_turn — Claude finished naturally.
max_tokens — hit the max_tokens limit. Response may be truncated.
tool_use — Claude wants to call a function. Must handle this explicitly.
stop_sequence — hit one of your stop sequences.

Always check stop_reason. If you receive tool_use and ignore it, Claude is waiting for your function result — it did not finish answering your question.

Model Selection

Three production models cover nearly all use cases. Choose by task complexity and cost tolerance:

Model	ID	Best For	Not For
Claude Opus 4	`claude-opus-4-8`	Complex multi-step reasoning, code generation from ambiguous specs, research synthesis	High-volume tasks (cost), simple classification
Claude Sonnet 4	`claude-sonnet-4-6`	Most production API tasks, customer-facing chat, structured extraction	Tasks where you need the cheapest option
Claude Haiku 4	`claude-haiku-4-5-20251001`	Classification, summarization, high-volume extraction, quick one-turn answers	Multi-step reasoning, long-form generation

Default to claude-sonnet-4-6 for any new feature. I start every integration on Sonnet and only swap to Haiku after running a sample of real production inputs through both models and comparing outputs — not benchmarks, actual outputs for your specific task. Migrate to Haiku only after confirming the output quality is acceptable for that specific task.

Streaming Responses

For responses longer than a paragraph, stream. A non-streaming call for a 2,000-token response waits 10–30 seconds before returning anything to the user. Streaming begins returning tokens in ~200ms.

def stream_response(system: str, prompt: str) -> None:
    with client.messages.stream(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        system=system,
        messages=[{"role": "user", "content": prompt}],
    ) as stream:
        for text in stream.text_stream:
            print(text, end="", flush=True)
    print()  # newline after stream ends

The with client.messages.stream() context manager handles connection cleanup. Inside the block, stream.text_stream yields each text delta as Claude generates it.

When to stream:

Any user-facing response longer than ~100 tokens.
Document generation, code generation, long explanations.

When not to stream:

Classification tasks where you need the complete label before doing anything.
Tool use — stream the full round trip only if you handle partial tool input JSON.
Batch processing jobs where individual response latency does not matter.

In practice, I default to streaming for anything user-facing and non-streaming for anything running in a background job. The distinction matters because mixing the two in the same codebase without clear conventions leads to subtle bugs when someone reuses a non-streaming helper in a latency-sensitive context.

Tool Use (Function Calling)

Tool use is a two-turn exchange. In turn one, Claude signals which function to call and with what arguments. Your application executes the function. In turn two, you send the result back, and Claude incorporates it into its final answer.

Turn one is not guaranteed to hold a single tool call. When a task decomposes into independent lookups, Claude returns multiple tool_use blocks in one content array against a single stop_reason: tool_use. Code that grabs "the" tool call with next(...) runs the first and silently drops the others; Claude then sees a tool_result for a call it never asked to have answered, and the response degrades in ways that don't throw an exception, so they slip through code review and manual testing.

Define a tool

CALCULATOR_TOOLS = [
    {
        "name": "calculator",
        "description": "Performs basic arithmetic. Use when the user asks for a calculation.",
        "input_schema": {
            "type": "object",
            "properties": {
                "operation": {
                    "type": "string",
                    "enum": ["add", "subtract", "multiply", "divide"],
                    "description": "The arithmetic operation to perform."
                },
                "a": {"type": "number", "description": "First operand."},
                "b": {"type": "number", "description": "Second operand."}
            },
            "required": ["operation", "a", "b"]
        }
    }
]

Handle the round trip

import json
from concurrent.futures import ThreadPoolExecutor

def use_tool(prompt: str) -> str:
    messages = [{"role": "user", "content": prompt}]

    # Turn 1: Claude may request one or more tool calls
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=CALCULATOR_TOOLS,
        messages=messages,
    )

    if response.stop_reason != "tool_use":
        # Claude answered directly — no tool call needed
        return response.content[0].text

    # Collect every tool_use block — a single turn can carry more than one
    tool_use_blocks = [b for b in response.content if b.type == "tool_use"]

    # Execute independent calculator calls concurrently; each is a pure,
    # side-effect-free function, so order doesn't matter and running them
    # sequentially would just add latency for no benefit.
    with ThreadPoolExecutor(max_workers=len(tool_use_blocks)) as pool:
        results = pool.map(
            lambda b: _run_calculator(b.input), tool_use_blocks
        )

    # Turn 2: one tool_result per tool_use_id, all in the same user message
    messages.append({"role": "assistant", "content": response.content})
    messages.append({
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": str(result),
            }
            for block, result in zip(tool_use_blocks, results)
        ],
    })

    final = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=CALCULATOR_TOOLS,
        messages=messages,
    )
    return final.content[0].text


def _run_calculator(args: dict) -> float:
    a, b, op = args["a"], args["b"], args["operation"]
    if op == "add":       return a + b
    if op == "subtract":  return a - b
    if op == "multiply":  return a * b
    if op == "divide":
        if b == 0:
            raise ValueError("Division by zero")
        return a / b
    raise ValueError(f"Unknown operation: {op}")

The key detail: messages.append({"role": "assistant", "content": response.content}) — you must include Claude's entire response object (including the tool use block) in the history before sending the tool result. Sending only the text content breaks the conversation. I've seen this cause a 400 BadRequestError in production because a developer extracted just the text from the assistant response and discarded the tool use block before appending — the API rejects the resulting message history as structurally invalid, and the error message doesn't point to the exact field.

Parallel versus sequential execution. Whether to run multiple tool calls concurrently is a decision about the tools, not the API — the API only requires that every tool_use_id from turn one gets a matching tool_result in turn two, in any order. Run them concurrently (thread pool for blocking I/O, asyncio.gather for async tools) when the calls are independent and side-effect-free, as with the calculator above; that's where the latency win is real, since three tool calls at 200ms each is 600ms sequential versus ~200ms concurrent. Run them sequentially, deliberately, when a later call depends on an earlier one's result, when the tools share a rate-limited resource, or when execution order matters for a side effect (a write followed by a read of what was just written). Defaulting to concurrency for tools that aren't actually independent is how you get race conditions that only show up under load.

Error Handling and Retries

Rate limit errors and transient server errors are inevitable at any meaningful scale. I've seen a well-tested integration start hitting RateLimitError the week after launch simply because a new feature tripled the request volume — the app had no retry logic, and every error surfaced directly to the user as a 500. Implement exponential backoff from day one:

import time
import anthropic

def _create_with_retry(
    messages: list,
    model: str,
    max_tokens: int,
    system: str = "",
    max_retries: int = 3,
) -> anthropic.types.Message:
    for attempt in range(max_retries):
        try:
            kwargs = {
                "model": model,
                "max_tokens": max_tokens,
                "messages": messages,
            }
            if system:
                kwargs["system"] = system
            return client.messages.create(**kwargs)
        except anthropic.RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait)
        except anthropic.APIStatusError as e:
            if e.status_code >= 500 and attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise

Common exceptions:

Exception	Cause	Action
`anthropic.RateLimitError`	Too many requests	Exponential backoff
`anthropic.APIStatusError` (5xx)	Server error	Retry with backoff
`anthropic.BadRequestError`	Invalid request (context too long, invalid params)	Do not retry — fix the request
`anthropic.AuthenticationError`	Bad API key	Do not retry — check env var

Check token count before sending a long conversation to avoid BadRequestError on context overflow:

token_count = client.messages.count_tokens(
    model="claude-sonnet-4-6",
    messages=messages,
)
print(f"Prompt uses {token_count.input_tokens} tokens")

Cost Management and Prompt Caching

Claude charges per token: input tokens (what you send) and output tokens (what Claude generates). Output tokens cost 3–5× more per token than input tokens. The usage breakdown appears in every response:

print(response.usage.input_tokens)   # tokens you sent
print(response.usage.output_tokens)  # tokens Claude generated

Prompt caching

If your application sends the same system prompt on every request (a common pattern), prompt caching can reduce input costs by 60–90%. Mark the cacheable prefix with cache_control:

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are a senior backend engineer...\n[very long system prompt]",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": user_question}],
)

On the first call, Anthropic caches the marked prefix. Subsequent calls within the cache TTL pay ~10% of the normal input price for cached tokens. The response includes cache statistics:

print(response.usage.cache_creation_input_tokens)  # tokens written to cache
print(response.usage.cache_read_input_tokens)       # tokens read from cache (cheap)

When caching pays off: system prompts over ~1,000 tokens with more than a few calls per day. I enable caching by default on any app with a fixed system prompt longer than 500 tokens — the implementation cost is two lines and the savings compound quickly once you're past a few hundred daily active users. For shorter prompts or low-volume applications, the overhead is negligible.

Common Mistakes

Not streaming long-form responses. A blocking call for a 2,000-token response times out in some HTTP clients and always delivers a poor user experience. Use client.messages.stream() for any response that takes more than ~1 second.
Ignoring stop_reason. If stop_reason is tool_use and you return response.content[0].text, you are returning a partial or empty string; Claude was waiting to give you a real answer after executing the tool. I've seen this ship to production as a bug where the API "randomly" returned empty responses on certain questions; questions that happened to trigger tool use. Always check stop_reason before extracting text.
Extracting only the first tool_use block. next(b for b in response.content if b.type == "tool_use") handles the common case and silently breaks the moment Claude returns two or three tool calls in one turn — the rest are dropped, and there's no exception to point you at the bug. Iterate response.content for all tool_use blocks and return one tool_result per tool_use_id.
Setting max_tokens too low. If max_tokens is smaller than the full response, Claude stops mid-sentence and stop_reason returns max_tokens. The response is valid JSON but the content is truncated. Set max_tokens generously; you are not charged for unused headroom.
Recreating the Anthropic() client on every request. The client maintains an HTTP connection pool internally. Instantiating it per-request wastes connection setup time and bypasses the pool. Create one instance at module level and reuse it.
Sending unbounded conversation history. Every previous turn counts toward the input token cost. For long conversations, implement a windowing strategy: keep the system prompt, the last N turns, and trim the middle. Use client.messages.count_tokens() before every send to catch overruns early.

Full Example

The companion code at ai-integration/claude-api-quickstart/src/main.py implements all patterns above as a ClaudeClient class:

from dotenv import load_dotenv
from src.main import ClaudeClient

load_dotenv()
claude = ClaudeClient()

# Basic message
print(claude.send_message(
    system="You are a concise technical explainer.",
    prompt="What is a vector embedding in one sentence?",
))

# Streaming
for chunk in claude.stream_response(
    system="You are a Python expert.",
    prompt="Explain Python generators in detail.",
):
    print(chunk, end="", flush=True)

# Tool use
print(claude.use_tool("What is 2847 multiplied by 193?"))

Setup:

cd ai-integration/claude-api-quickstart
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env       # add your key
python -m src.main

Full source: GitHub link

State: The Conversation Turn Model

Conclusion

The difference between a Claude integration that works in a demo and one that holds up in production is not the model — it's whether you stream, whether you handle tool use as a complete round trip, and whether you have a cost strategy before your usage scales. Most production failures I've traced come back to one of those three. Ship an integration that gets all three right from the start, and you will spend your time building features instead of debugging silent errors and explaining surprise billing cycles to stakeholders.

Amazon API Gateway: REST vs HTTP APIs, Explained via the AWS CLI

Bry — Tue, 14 Jul 2026 15:00:00 +0000

Key Points

REST API and HTTP API are two separate products under one brand name, with two separate CLI command namespaces — aws apigateway and aws apigatewayv2. They are not versions of each other.
HTTP API costs $1.00 per million calls versus REST API's flat $3.50 per million — a 71% difference that compounds fast at scale.
Pick REST API only when you need something HTTP API structurally cannot do: API keys, per-client usage plans, AWS WAF, request validation, or private (VPC-only) endpoints.
The CLI reveals the real gap between them better than any feature table: building the same Lambda-backed endpoint takes one command on HTTP API and five on REST API.
Tear down what you build. Both products bill for idle resources, and orphaned stages are the most common line item nobody remembers creating.

Prerequisites

CLI/SDK version tested against: aws-cli/2.35.x (current stable as of this writing — the apigatewayv2 and apigateway command sets are stable across 2.x minor releases, but always run aws --version before following along)
An AWS account with an IAM user or role that has apigateway:* and lambda:* permissions, and a default region configured (aws configure)
A deployed Lambda function to integrate against — the examples below use a function named user-lookup

Introduction

Every AWS API Gateway tutorial I've read picks a product on page one and never explains why. Half of them build a REST API with create-resource and put-method chains that look like plumbing. The other half quick-create an HTTP API in one line and call it a day. Neither tells you when the other approach would have been the better call — and I've watched teams build a REST API out of habit, hit the $3.50-per-million bill at scale, and only then discover HTTP API existed.

The two products share a brand name and almost nothing else under the hood. They have separate CLI command namespaces, separate feature sets, and a 3.5x price difference that AWS designed on purpose, not as an afterthought. Understanding which one you're actually building — and why — matters more than memorizing either command sequence.

This article builds the identical Lambda-backed endpoint twice: once on HTTP API, once on REST API, entirely from the AWS CLI. You'll see where the commands diverge, where they can't diverge because one product simply lacks the feature, and which one to default to for your next project.

Two Products, Not Two Versions

AWS API Gateway is a brand covering three products: REST API, HTTP API, and WebSocket API. REST API launched in 2015. HTTP API launched in 2019 as a deliberately smaller product — AWS's own announcement framed it as coverage for the roughly 80% of REST API customers who only needed Lambda proxy integration, JWT auth, and CORS, and were paying REST API prices for features they never touched.

Diagram: One brand, two CLI namespaces, non-overlapping feature sets.

That last point trips people up the most: aws apigateway and aws apigatewayv2 are not "v1 and v2 of the same thing" the way S3's SDK versions are. They are two independent command trees. A script written for REST API will not run against HTTP API with a find-and-replace.

Building the Same Endpoint on HTTP API

Start with HTTP API, because it's shorter and shows what "quick create" actually collapses into one call.

# Quick-create an HTTP API backed directly by a Lambda function.
# This single command creates the API, a default catch-all route,
# a Lambda integration, and an auto-deploying default stage.
aws apigatewayv2 create-api \
  --name user-lookup-http \
  --protocol-type HTTP \
  --target "arn:aws:lambda:us-east-1:123456789012:function:user-lookup"

That one call is doing the work of five REST API calls, which is the point. Quick create only works for a single catch-all route. The moment you need more than one route with different backends, you build it up explicitly:

# Explicit build — needed once you have more than one route.
API_ID=$(aws apigatewayv2 create-api \
  --name user-lookup-http \
  --protocol-type HTTP \
  --query 'ApiId' --output text)

INTEGRATION_ID=$(aws apigatewayv2 create-integration \
  --api-id "$API_ID" \
  --integration-type AWS_PROXY \
  --integration-uri "arn:aws:lambda:us-east-1:123456789012:function:user-lookup" \
  --payload-format-version "2.0" \
  --query 'IntegrationId' --output text)

aws apigatewayv2 create-route \
  --api-id "$API_ID" \
  --route-key "GET /users/{userId}" \
  --target "integrations/$INTEGRATION_ID"

# HTTP API stages auto-deploy by default — no separate deployment call needed
aws apigatewayv2 create-stage \
  --api-id "$API_ID" \
  --stage-name '$default' \
  --auto-deploy

Four commands, no separate deployment step because $default auto-deploys on every change. Add a JWT authorizer — the feature HTTP API supports natively and REST API cannot without a Lambda authorizer standing in for it:

aws apigatewayv2 create-authorizer \
  --api-id "$API_ID" \
  --authorizer-type JWT \
  --identity-source '$request.header.Authorization' \
  --name user-pool-jwt \
  --jwt-configuration '{"Audience":["https://api.example.com"],"Issuer":"https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX"}'

Grant API Gateway permission to invoke the Lambda, and the endpoint is live:

aws lambda add-permission \
  --function-name user-lookup \
  --statement-id apigw-http-invoke \
  --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:us-east-1:123456789012:${API_ID}/*/*/users/*"

curl "https://${API_ID}.execute-api.us-east-1.amazonaws.com/users/usr_42"

Total: five commands from zero to a JWT-protected, auto-deploying endpoint.

Building the Same Endpoint on REST API

Now the same endpoint on REST API. Structurally, REST API models resources as a tree — you create the API, then walk down from the root resource creating child resources, then attach an HTTP method and integration to each resource individually.

Diagram: REST API's resource-tree model requires an explicit deployment step that HTTP API's auto-deploy stages skip entirely.

API_ID=$(aws apigateway create-rest-api \
  --name user-lookup-rest \
  --endpoint-configuration types=REGIONAL \
  --query 'id' --output text)

ROOT_ID=$(aws apigateway get-resources \
  --rest-api-id "$API_ID" \
  --query 'items[?path==`/`].id' --output text)

USERS_ID=$(aws apigateway create-resource \
  --rest-api-id "$API_ID" \
  --parent-id "$ROOT_ID" \
  --path-part users \
  --query 'id' --output text)

USERID_RESOURCE=$(aws apigateway create-resource \
  --rest-api-id "$API_ID" \
  --parent-id "$USERS_ID" \
  --path-part '{userId}' \
  --query 'id' --output text)

aws apigateway put-method \
  --rest-api-id "$API_ID" \
  --resource-id "$USERID_RESOURCE" \
  --http-method GET \
  --authorization-type NONE

aws apigateway put-integration \
  --rest-api-id "$API_ID" \
  --resource-id "$USERID_RESOURCE" \
  --http-method GET \
  --type AWS_PROXY \
  --integration-http-method POST \
  --uri "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:user-lookup/invocations"

# REST API has no auto-deploy — every change requires an explicit deployment
aws apigateway create-deployment \
  --rest-api-id "$API_ID" \
  --stage-name prod

Seven commands versus HTTP API's five, and that's before adding auth — REST API has no native JWT authorizer at all. You'd add a Lambda authorizer via create-authorizer --type TOKEN, which is its own Lambda function to write, deploy, and maintain, purely to validate a token that HTTP API checks natively with one --jwt-configuration flag. AUTHORIZATION_TYPE=NONE above is intentionally the simplest case to keep the comparison fair — swapping in Cognito or a Lambda authorizer adds two more commands on the REST API side and zero on the HTTP API side.

That gap is the entire argument for defaulting to HTTP API. Not the price alone — the operational surface. Every additional resource, method, and integration on REST API is something you version, test, and can misconfigure. HTTP API's route-based model has fewer places to get it wrong.

The Feature Gap That Actually Justifies REST API

None of this means REST API is obsolete. It means most projects don't need what it offers. Per AWS's own comparison documentation, REST API supports several things HTTP API structurally cannot do at all:

Feature	REST API	HTTP API
API keys + usage plans	Yes	No
Per-client rate limiting	Yes	No
AWS WAF integration	Yes	No
Request validation (schema)	Yes	No
Private (VPC-only) endpoints	Yes	No
Response caching	Yes	No
Mock integrations	Yes	No
JWT authorizer (native)	No	Yes
Auto-deploying stages	No	Yes
Private integrations via AWS Cloud Map	No	Yes

If you're selling API access to third-party developers and need to issue API keys with per-key quotas, that's REST API, full stop — HTTP API has no equivalent mechanism, not a smaller version of one. Same for WAF: if compliance requires a web application firewall in front of the gateway, REST API is your only option between the two. I've built exactly one REST API in the last two years for a client billing external partners per API key against a usage plan — every other new project defaulted to HTTP API.

Cost at Scale

The sticker prices understate how fast this compounds. At 500 million requests a month:

	HTTP API	REST API
First 300M	$300 (at $1.00/M)	$1,050 (at $3.50/M)
Remaining 200M	$180 (at $0.90/M)	$700
Monthly total	$480	$1,750

That's before data transfer, which is identical on both ($0.09/GB after the first 100 GB). A team that defaults to REST API out of habit on a 500M-request workload is paying an extra $1,270 a month for features it may never touch. Multiply that by however many services in your org made the same default choice and it stops being a rounding error.

Common Mistakes

Mistake 1: Choosing REST API because older tutorials only cover it
Most CLI tutorials predate HTTP API's 2019 launch or were never updated. If a walkthrough uses aws apigateway create-rest-api and never mentions apigatewayv2, it's not wrong, just incomplete — check whether you actually need REST API's feature set before copying it.

Mistake 2: Assuming apigatewayv2 supports API keys
It doesn't, and there's no workaround at the gateway layer. Teams that need lightweight per-client identification on HTTP API end up implementing it themselves — a custom header checked in the Lambda, or a JWT claim — rather than getting it for free the way REST API's usage plans provide it.

Mistake 3: Forgetting the deployment step on REST API
Unlike HTTP API's auto-deploying $default stage, REST API changes are invisible until you run create-deployment. I've debugged more than one "my change isn't showing up" ticket that was just a missing deployment call after a put-integration update.

Mistake 4: Leaving orphaned APIs after testing
Both products bill nothing for an idle API with zero traffic, but Lambda add-permission grants and unused custom domain mappings pile up and become a mess to audit six months later. Clean up as you go.

Teardown

Both products are cheap to tear down completely, and you should — leftover test APIs are how AWS bills quietly creep up.

# HTTP API
aws apigatewayv2 delete-api --api-id "$API_ID"

# REST API
aws apigateway delete-rest-api --rest-api-id "$API_ID"

Full teardown script, including the Lambda permission cleanup, is in the companion repo below.

Production Considerations

Performance: HTTP API adds roughly 6 ms of median gateway overhead; REST API adds roughly 11 ms. At p99, the gap narrows because both are dominated by backend latency, not gateway overhead — don't over-index on this number when choosing.

Security: If you're on HTTP API and need WAF-equivalent protection, put CloudFront with AWS WAF in front of it — HTTP API supports CloudFront origins natively. This is the standard workaround and it works well, but it's an extra piece of infrastructure REST API gives you natively.

Cost: Re-run the math above whenever traffic grows 5-10x. A choice that made sense at 10M requests a month can look very different at 500M.

Monitoring: Both emit CloudWatch metrics. Only REST API emits execution logs and X-Ray traces natively — on HTTP API, instrument tracing inside the Lambda itself if you need request-level tracing.

Full Example: Build-and-Verify Script

The companion repository includes a complete bash script that builds both APIs, verifies each with a live curl, and tears both down. The core verification logic:

#!/usr/bin/env bash
set -euo pipefail

verify_endpoint() {
  local url="$1"
  local label="$2"
  local status
  status=$(curl -s -o /dev/null -w '%{http_code}' "$url")
  if [[ "$status" == "200" ]]; then
    echo "OK   $label -> $status"
  else
    echo "FAIL $label -> $status"
    exit 1
  fi
}

verify_endpoint "https://${HTTP_API_ID}.execute-api.${AWS_REGION}.amazonaws.com/users/usr_42" "HTTP API"
verify_endpoint "https://${REST_API_ID}.execute-api.${AWS_REGION}.amazonaws.com/prod/users/usr_42" "REST API"

Full source with setup, teardown, and verification scripts: GitHub → cloud-apis/amazon-api-gateway-cli/

Conclusion

Default to HTTP API. It's cheaper, has fewer commands to build and maintain, and natively supports JWT auth — the thing most new services actually need. Reach for REST API only when you specifically need API keys with usage plans, WAF, request validation, caching, or private VPC-only endpoints — features HTTP API doesn't have a smaller version of, because it was never built to. The CLI makes this concrete in a way the marketing pages don't: five commands versus seven isn't just fewer keystrokes, it's fewer places for a misconfigured resource or a forgotten deployment to bite you in production.

REST API Design Best Practices: A Field Guide for Backend Developers

Bry — Tue, 07 Jul 2026 15:00:00 +0000

Key Points

Name resources with nouns and plural forms (/users, /orders/{id}), never verbs (/getUser, /createOrder).
Match HTTP methods to their RFC-defined semantics — GET is safe and idempotent, POST is neither, PATCH is partial update.
Return RFC 7807 Problem Details for all error responses — a consistent, machine-readable error shape your consumers can rely on.
Use URL path versioning (/v1/) — it is visible, cacheable, and debuggable without header inspection.
Cursor-based pagination scales to any dataset size; offset-based pagination breaks under concurrent writes.

Introduction

An API that ignores HTTP semantics, uses verbs in URLs, and returns { "error": "something went wrong" } is technically functional. It also generates a steady stream of support tickets, misconfigured clients, and integration bugs that consume engineering time for as long as the API exists.

REST is not a standard — it is a set of architectural constraints described by Roy Fielding in 2000. Most APIs that call themselves RESTful violate several of those constraints and still work fine. The practices in this article are not about philosophical purity. They are about making choices that reduce friction for the developers consuming your API, reduce bugs at integration points, and reduce maintenance burden over a long API lifetime.

I've shipped and maintained REST APIs across enough companies to know that the decisions you make in week one are the ones you're still apologizing for in year three. This article is the set of defaults I'd apply if I were starting a new API today — with a reference implementation that shows all of them working together.

Architecture Overview

Diagram: Request flow from client through API Gateway, token validation, business logic, and data layer.

Resource Design: Naming and Hierarchy

Resources are the nouns in your API. Every URL identifies a resource, not an action.

Rule: Use plural nouns for collections, singular for specific members.

GET    /v1/articles          → list all articles
POST   /v1/articles          → create an article
GET    /v1/articles/{id}     → get one article
PATCH  /v1/articles/{id}     → partially update one article
DELETE /v1/articles/{id}     → delete one article

Never use verbs in paths:

❌ /v1/getArticle
❌ /v1/createArticle
❌ /v1/articles/delete
✓  /v1/articles/{id}   with DELETE method

For sub-resources, express ownership through hierarchy — but stop at two levels. Deeper than two levels signals the resource model needs rethinking.

GET /v1/articles/{id}/comments      ← acceptable
GET /v1/articles/{id}/comments/{cid}/replies/{rid}  ← too deep, model differently

Resource Data Model

HTTP Methods and Status Codes

Method Semantics

Method	Safe	Idempotent	Body	When to use
`GET`	Yes	Yes	No	Fetch a resource or collection. Never mutate.
`POST`	No	No	Yes	Create a new resource. Each call may produce a new resource.
`PUT`	No	Yes	Yes	Replace a resource completely. Must send the full representation.
`PATCH`	No	No	Yes	Partial update. Send only the fields to change.
`DELETE`	No	Yes	No	Remove a resource. Idempotent — deleting twice is not an error.

Safe means the method must not change server state.

Idempotent means calling it N times has the same effect as calling it once.

Use PATCH over PUT for updates unless you genuinely need full replacement. Requiring clients to send the entire resource for a title change is wasteful and error-prone.

Status Codes That Matter

Code	Meaning	When
`200 OK`	Success with body	GET, PATCH, PUT responses
`201 Created`	Resource created	POST success — include `Location` header
`204 No Content`	Success, no body	DELETE success
`400 Bad Request`	Malformed request	Missing required field, invalid format
`401 Unauthorized`	Not authenticated	No token or invalid token
`403 Forbidden`	Authenticated but not allowed	Correct token, wrong permissions
`404 Not Found`	Resource does not exist	ID not in database
`409 Conflict`	State conflict	Duplicate create, optimistic lock failure
`422 Unprocessable Entity`	Valid format, invalid content	Passes JSON parse but fails business validation
`429 Too Many Requests`	Rate limit hit	Include `Retry-After` header
`500 Internal Server Error`	Server bug	Never expose stack traces

Do not return 200 OK with an error payload. A client that checks the status code first — which all good clients do — will miss your error.

Request-Response Sequence

Response Shape: Data and Errors

Success Response

Keep success responses flat when possible. Wrap in a data envelope only when you need top-level metadata alongside the resource (e.g., pagination).

// Single resource — no wrapper needed
{
  "id": "abc123",
  "title": "REST API Design Best Practices",
  "authorId": "usr_789",
  "status": "published",
  "createdAt": "2026-10-01T09:00:00Z",
  "updatedAt": "2026-10-01T09:00:00Z"
}

// Collection — wrapper needed for pagination metadata
{
  "data": [...],
  "pagination": {
    "limit": 20,
    "next_cursor": "abc124"
  }
}

Use ISO 8601 for all timestamps with UTC timezone (Z suffix). Never return Unix epoch integers — they require client-side conversion and obscure the value during debugging.

Error Response — RFC 7807 Problem Details

RFC 7807 defines a standard error response format. Use it. Your consumers can write error handling once and it works across all your endpoints.

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Article Not Found",
  "status": 404,
  "detail": "No article with id 'abc999' exists.",
  "instance": "/v1/articles/abc999"
}

Set Content-Type: application/problem+json on all error responses.

import { Response } from 'express';

function problem(
  res: Response,
  status: number,
  title: string,
  detail: string,
  instance?: string,
): void {
  const body: Record<string, unknown> = {
    type: `https://api.example.com/errors/${status}`,
    title,
    status,
    detail,
  };
  if (instance) body.instance = instance;
  res.status(status).contentType('application/problem+json').json(body);
}

// Usage
problem(res, 404, 'Article Not Found', `No article with id '${id}' exists.`, req.path);

Versioning

You will change your API. Version it from day one.

Strategy	Example	Pros	Cons
URL path	`/v1/articles`	Visible, cacheable, loggable, bookmarkable	URL "leaks" version — semantic purists object
Request header	`API-Version: 2026-01-01`	Clean URLs	Invisible, hard to test in browser, can't cache differently
Query param	`/articles?version=1`	Easy to test	Pollutes query space, gets stripped by some proxies
Accept header	`Accept: application/vnd.api.v2+json`	RFC-compliant content negotiation	Verbose, poor tooling support

Use URL path versioning. You'll hear that it violates REST semantics — typically from people who've never had to track down a versioning bug in production logs where the client was silently sending the wrong header. Visibility in logs, cache keys, and browser testability are real, daily benefits. The semantic purity objection is theoretical.

State Diagram: API Version Lifecycle

Announce deprecation in response headers: Deprecation: true, Sunset: Sat, 01 Jan 2028 00:00:00 GMT.

Pagination and Filtering

Cursor vs Offset

Criteria	Offset (`?page=2&limit=20`)	Cursor (`?cursor=abc&limit=20`)
Performance at scale	Degrades — `OFFSET 1000000` is slow	Constant — indexed seek
Stable under concurrent writes	No — items shift between pages	Yes — cursor anchors position
Seekable to arbitrary page	Yes	No — must walk forward
Implementation complexity	Low	Medium

Use cursor pagination. OFFSET 100000 is a slow table scan dressed up as a query parameter. I've seen this exact pattern take down a read replica during a traffic spike — the query plan looked fine in development on 5,000 rows, then became catastrophic at 2 million under load. Offset pagination is fine for 50-row config lists that never change. For anything that grows or updates frequently, use cursor pagination from day one. Retrofitting it later is painful.

app.get('/v1/articles', (req: Request, res: Response) => {
  const limit = Math.min(parseInt((req.query.limit as string) ?? '20', 10), 100);
  const cursor = req.query.cursor as string | undefined;
  const authorId = req.query.author_id as string | undefined;
  const status = req.query.status as string | undefined;

  let items = Array.from(db.values());
  if (authorId) items = items.filter(a => a.authorId === authorId);
  if (status)   items = items.filter(a => a.status === status);

  let start = 0;
  if (cursor) {
    const idx = items.findIndex(a => a.id === cursor);
    if (idx !== -1) start = idx + 1;
  }

  const page = items.slice(start, start + limit);
  const nextCursor = page.length === limit ? page[page.length - 1].id : null;

  res.json({ data: page, pagination: { limit, next_cursor: nextCursor } });
});

Filtering goes in query parameters. Sorting too:

GET /v1/articles?status=published&author_id=usr_789&sort=-createdAt&limit=20

Convention: prefix - means descending (-created_at = newest first).

Security Fundamentals

Authentication

Pass credentials in the Authorization header. Never in URLs — URLs appear in server logs, browser history, and proxy caches.

# Correct
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/articles

# Wrong — token in logs forever
curl https://api.example.com/v1/articles?token=$TOKEN

Request Authentication Flow

HTTPS Only

Enforce HTTPS at the gateway level. Reject HTTP with 301 Moved Permanently to the HTTPS equivalent. Never accept credentials over plain HTTP.

Rate Limiting Response

When you rate-limit a request, return 429 Too Many Requests with these headers:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1727780460

Idempotency Keys

POST is not idempotent — calling it twice creates two resources. Networks are unreliable. A client that retries a timed-out POST /v1/orders could create a duplicate charge.

The solution: clients attach a unique Idempotency-Key header. The server stores the response for that key. If the same key arrives again, return the cached response without re-executing the operation.

# First request — creates the article
curl -X POST https://api.example.com/v1/articles \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello","content":"...","authorId":"usr_1"}'
# → 201 Created

# Retry with same key (network timeout, client retries)
curl -X POST https://api.example.com/v1/articles \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  ...
# → 201 Created (same response, no second article created)

// Middleware: check and store idempotency keys
// Use Redis with a TTL (e.g., 24 h) in production — Map is in-memory only
const idempotencyStore = new Map<string, { status: number; body: unknown }>();

function withIdempotency(
  handler: (req: Request, res: Response) => void,
): (req: Request, res: Response) => void {
  return (req, res) => {
    const key = req.headers['idempotency-key'] as string | undefined;
    if (key) {
      const cached = idempotencyStore.get(key);
      if (cached) {
        res.status(cached.status).json(cached.body);
        return;
      }
      const originalJson = res.json.bind(res);
      res.json = (body) => {
        idempotencyStore.set(key, { status: res.statusCode, body });
        return originalJson(body);
      };
    }
    handler(req, res);
  };
}

// Apply to any non-idempotent route
app.post('/v1/articles', withIdempotency((req, res) => {
  // ... normal create logic
}));

Idempotency keys matter most for payment, order, and email-send endpoints. Stripe, PayPal, and Shopify all implement this pattern. Your key store needs a TTL — a key that lives forever leaks memory; 24 hours is the Stripe standard.

Common Mistakes

Mistake 1: Verbs in resource names

POST /v1/sendEmail treats the action as the resource. The resource is the email — the action is the HTTP method. POST /v1/emails is correct. If an action genuinely has no resource noun, use a sub-resource: POST /v1/articles/{id}/publish.

Mistake 2: Returning 200 OK for errors

Returning { "success": false, "error": "not found" } with 200 OK means clients must parse and inspect the body on every response to detect failures. HTTP status codes exist precisely to avoid this. Use them.

Mistake 3: Swallowing 404 vs 403

Returning 404 Not Found when the resource exists but the caller lacks access is both a correctness bug and a security vulnerability — you're leaking resource existence to unauthorized callers. The correct response is 403 Forbidden. Return 404 only when the resource genuinely does not exist (or when you deliberately want to hide its existence — which must be an intentional, documented choice, not an accident).

Mistake 4: Offset pagination in high-traffic collections

SELECT * FROM articles ORDER BY created_at LIMIT 20 OFFSET 10000 requires the database to read and discard 10,000 rows. I've debugged production incidents caused by exactly this — the query looks fine on 5,000 rows in development, then becomes a full table scan in disguise at 2 million rows under peak load. Switch to cursor-based pagination: WHERE id > $cursor ORDER BY id LIMIT 20.

Mistake 5: No consistent error shape

An API that returns { "message": "..." } on some errors, { "error": { "code": "...", "description": "..." } } on others, and a plain HTML 500 page on unhandled exceptions forces consumers to write separate error handling for every possible failure mode. Adopt RFC 7807 and return the same shape everywhere — including unhandled 500s.

Full Example: Complete Express TypeScript Implementation

Everything covered above in one runnable file. Copy it, run npm run dev, and use the curl commands below to verify each behavior.

import express, { Request, Response } from 'express';
import { z } from 'zod';
import { randomUUID } from 'crypto';

const app = express();
app.use(express.json());

// Types

interface Article {
  id: string;
  title: string;
  content: string;
  authorId: string;
  status: 'draft' | 'published';
  createdAt: string;
  updatedAt: string;
}

const db = new Map<string, Article>();

// Helpers

function nowIso(): string {
  return new Date().toISOString();
}

function problem(res: Response, status: number, title: string, detail: string, instance?: string): void {
  const body: Record<string, unknown> = {
    type: `https://api.example.com/errors/${status}`,
    title,
    status,
    detail,
  };
  if (instance) body.instance = instance;
  res.status(status).contentType('application/problem+json').json(body);
}

// Validation schemas

const ArticleCreateSchema = z.object({
  title: z.string().min(1),
  content: z.string().min(1),
  authorId: z.string().min(1),
});

const ArticleUpdateSchema = z.object({
  title: z.string().min(1).optional(),
  content: z.string().min(1).optional(),
});

// Routes

// POST /v1/articles — create, 201 + Location header
app.post('/v1/articles', (req: Request, res: Response) => {
  const parsed = ArticleCreateSchema.safeParse(req.body);
  if (!parsed.success) {
    problem(res, 422, 'Validation Error', parsed.error.issues.map(i => i.message).join(', '));
    return;
  }
  const id = randomUUID();
  const ts = nowIso();
  const article: Article = { id, ...parsed.data, status: 'draft', createdAt: ts, updatedAt: ts };
  db.set(id, article);
  res.status(201).setHeader('Location', `/v1/articles/${id}`).json(article);
});

// GET /v1/articles — list with cursor pagination and filtering
app.get('/v1/articles', (req: Request, res: Response) => {
  const limit = Math.min(parseInt((req.query.limit as string) ?? '20', 10), 100);
  const cursor   = req.query.cursor    as string | undefined;
  const authorId = req.query.author_id as string | undefined;
  const status   = req.query.status   as string | undefined;

  let items = Array.from(db.values());
  if (authorId) items = items.filter(a => a.authorId === authorId);
  if (status)   items = items.filter(a => a.status === status);

  let start = 0;
  if (cursor) {
    const idx = items.findIndex(a => a.id === cursor);
    if (idx !== -1) start = idx + 1;
  }

  const page = items.slice(start, start + limit);
  const nextCursor = page.length === limit ? page[page.length - 1].id : null;
  res.json({ data: page, pagination: { limit, next_cursor: nextCursor } });
});

// GET /v1/articles/:id
app.get('/v1/articles/:id', (req: Request, res: Response) => {
  const article = db.get(req.params.id);
  if (!article) { problem(res, 404, 'Article Not Found', `No article with id '${req.params.id}'.`, req.path); return; }
  res.json(article);
});

// PATCH /v1/articles/:id — partial update
app.patch('/v1/articles/:id', (req: Request, res: Response) => {
  const article = db.get(req.params.id);
  if (!article) { problem(res, 404, 'Article Not Found', `No article with id '${req.params.id}'.`, req.path); return; }

  const parsed = ArticleUpdateSchema.safeParse(req.body);
  if (!parsed.success) { problem(res, 422, 'Validation Error', parsed.error.issues.map(i => i.message).join(', ')); return; }

  if (parsed.data.title   !== undefined) article.title   = parsed.data.title;
  if (parsed.data.content !== undefined) article.content = parsed.data.content;
  article.updatedAt = nowIso();
  res.json(article);
});

// POST /v1/articles/:id/publish — action as sub-resource
app.post('/v1/articles/:id/publish', (req: Request, res: Response) => {
  const article = db.get(req.params.id);
  if (!article) { problem(res, 404, 'Article Not Found', `No article with id '${req.params.id}'.`, req.path); return; }
  if (article.status === 'published') { problem(res, 409, 'Already Published', `Article '${req.params.id}' is already published.`, req.path); return; }
  article.status = 'published';
  article.updatedAt = nowIso();
  res.json(article);
});

// DELETE /v1/articles/:id — 204 No Content
app.delete('/v1/articles/:id', (req: Request, res: Response) => {
  if (!db.has(req.params.id)) { problem(res, 404, 'Article Not Found', `No article with id '${req.params.id}'.`, req.path); return; }
  db.delete(req.params.id);
  res.status(204).send();
});

app.listen(3000, () => console.log('API running on http://localhost:3000'));

Run it:

npm install
npm run dev

Test the full cycle:

# Create
curl -s -X POST http://localhost:3000/v1/articles \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello","content":"World","authorId":"usr_1"}' | jq

# List with filter
curl -s "http://localhost:3000/v1/articles?author_id=usr_1&limit=5" | jq

# Publish (action as sub-resource)
curl -s -X POST http://localhost:3000/v1/articles/{id}/publish | jq

# Delete — expect 204
curl -s -o /dev/null -w "%{http_code}" -X DELETE http://localhost:3000/v1/articles/{id}

Full source with tests: GitHub link

Conclusion

REST API design is a set of decisions you make once and live with for years. The ones I see cause the most pain aren't exotic — they're the basics: verbs in URLs, inconsistent error shapes, offset pagination on growing datasets, no versioning plan. None of this is new. RFC 7807 has existed since 2016. Cursor pagination predates it by decades.

The reason these mistakes keep appearing in fresh codebases is that nothing stops you from making them. Frameworks don't enforce it. Tutorials skip it. You have to choose these defaults deliberately.

Now you have a reason to.

DEV Community: Bry

API Gateway Patterns: AWS vs Azure vs GCP

Key Points

Introduction

What an API Gateway Does

Request Flow Through a Gateway

AWS API Gateway

HTTP API vs REST API

Lambda Integration

The Cold Start Gotcha

Azure API Management (APIM)

The Policy Engine

Developer Portal

Pricing Tiers

GCP: API Gateway, Cloud Endpoints, and Apigee

GCP API Gateway — OpenAPI-Driven Configuration

The GCP Quota Gotcha

Feature Comparison

Common Patterns

Backend for Frontend (BFF)

API Aggregation

Protocol Translation

API Lifecycle Management

Choosing the Right Gateway

Common Mistakes

Production Considerations

Full Example: API Aggregation Service (TypeScript)

Conclusion

Further Reading

Story Points After AI: When Velocity Metrics Stop Meaning What They Used To

Key Points

Introduction

Old Velocity Metrics vs. Post-AI Delivery Metrics

Where This Is Likely Headed

Questions to Ask Your Team

Conclusion

Further Reading

AWS EventBridge: Event Buses and Rules You Can Script from Day One

Key Points

Prerequisites

Introduction

Bus, Rules, Targets: The Three Pieces

Building It From the CLI

Designing Around the Payload-Chunking Rule

Archive and Replay

Common Mistakes

Production Considerations

Full Example: Teardown Script

Conclusion

Further Reading

Why the Man-Month Is Dying: How AI Broke IT Services' Oldest Pricing Unit

Key Points

Introduction

Man-Month Billing vs. What Replaced It

How the Transition is Expected to Unfolded, 2026 onwards

Questions to Ask Your Team

Conclusion

Further Reading

API Gateway for Business Leaders: What It Is, Why It Matters, and How to Adopt It

Key Points

Introduction

What Is an API Gateway?

Before and After

Key Benefits

With Gateway vs Without Gateway

How It Works (Without the Code)

Cloud Provider Options

Pros and Cons

Advantages

Disadvantages and Risks

Is an API Gateway Right for You?

Adoption Roadmap

Phase 1: Evaluate (Weeks 1–2)

Phase 2: Pilot (Weeks 3–6)

Phase 3: Expand (Months 2–4)

Phase 4: Standardize (Month 4 onward)

Cost Considerations

Questions to Ask Your Engineering Team

Conclusion

Further Reading