HTTP vs WebSockets, API Gateway Stages, and Versioning Strategies That Survive Deprecation

On May 8, 2026, Amazon API Gateway still differentiates REST, HTTP, and WebSocket APIs with different billing and timeout surfaces. The number that still shocks architecture reviews: REST APIs integrate with a maximum 29-second timeout for many synchronous integrations—long-running work must go async or move execution to a service that tolerates longer compute windows with different controls.

For pattern coverage beyond this note, see our existing API Gateway REST/HTTP/WebSocket patterns article; this field note focuses on decision tension and versioning that survives deprecation.

Reproduce this — Versioning checklist template: examples/architecture-blog-2026/api-design/versioning-conventions.md

HTTP (request/response) when it wins

Default for CRUD JSON, cache-friendly GETs, and stateless authentication (JWT/OAuth). Pair with:

• AWS WAF on regional APIs or CloudFront distributions (WAF beyond basics).
• IAM/authorizers aligned to least privilege (IAM best practices).

WebSockets when they win

Choose WebSockets when:

• The server must push many small updates (tick data, collaborative editing).
• You accept stateful connection troubleshooting (stale connections, proxy idle timeouts).

Costs accrue per message and connection-minute—model them before broadcasting chat-scale fan-out.

Avoid WebSockets when mobile networks and corporate proxies make long-lived ports flaky without a fallback polling path.

AppSync (GraphQL + subscriptions)

When your clients need flexible reads and subscription channels with managed auth integration, AWS AppSync often beats hand-rolled GraphQL on Lambda—evaluate resolver heat and caching separately from REST gateway pricing.

Versioning strategies (opinionated)

Pick one primary signal:

1. URL prefix (/v2026-05/...) — blunt, CDN-friendly, easy WAF paths.
2. Header contract (Accept vendor MIME) — avoids URL churn; demands consistent observability tags.
3. Stage-based (prod, canary) — operational, not semantic versioning alone—pair with semantic headers or URLs so customers know what they parse.

Opinionated take — Public third-party APIs should ship URL major versions and publish Sunset headers (RFC 8594) even if you love headers internally. External developers grep paths, not MIME types, at 2 AM.

What broke: the “silent deprecation”

An internal team deleted a stage believing it unused. Mobile clients still referenced the stage URL embedded in a legacy binary. Error budgets burned before anyone correlated 403/404 spikes with an infrastructure changefront.

Fix: deprecation registers + synthetic clients + minimum N+2 release overlap before decommission.

For service decomposition context, contrast with microservices vs monolith on AWS.

What This Post Doesn’t Cover

• VPC Lattice service networking vs API Gateway—different abstraction (service mesh vs edge HTTP).
• Istio/Envoy on EKS — see service mesh articles if east-west mTLS dominates.

If You Only Do One Thing

Attach per-route CloudWatch metrics (4xx/5xx, integration latency) to the same dashboard as client release versions parsed from headers you already log.

What to Do This Week

1. Inventory all execute-api stage URLs in mobile binaries and partner PDFs; anything not in Terraform gets a ticket.
2. Confirm every >10s synchronous integration has an SQS/Step Functions exit before API Gateway timeout cliffs.
3. Add WAF rate-based rules to public WebSocket $connect routes if you have not already—credential stuffing loves connect storms.

When ingress tuning intersects Lambda cold paths, cross-read ingress and cold-start field notes.