client -> API Gateway -> Lambda/service -> database

- public contract,
- authentication boundary,
- throttling boundary,
- request validation boundary,
- routing boundary,
- transformation boundary,
- observability boundary,
- blast-radius boundary,
- backward-compatibility boundary,
- long-running workflow boundary,
- database write protection boundary.

POST /orders
GET /orders/{id}
POST /orders/{id}/cancel
GET /orders/{id}/events

apakah request ini command atau query?
apakah butuh idempotency?
apakah boleh retry?
apakah response harus read-after-write accurate?
apakah operasi bisa selesai dalam request timeout?
apakah backend dependency bisa overload?
apakah database transaction boundary jelas?

REST API
HTTP API
WebSocket API

- request validation yang kuat di gateway,
- API keys dan usage plans,
- advanced request/response transformation,
- gateway response customization,
- mature feature set,
- private/regional/edge-oriented REST deployment needs,
- kontrol detail terhadap method, resource, stage, model, mapping, deployment.

- public payment API,
- partner onboarding API,
- regulatory submission API,
- enterprise B2B API,
- API dengan strict schema validation di gateway,
- API yang membutuhkan usage plan per client.

+ feature lengkap,
+ governance kuat,
+ request validation dan model matang,
+ transformasi detail,
- konfigurasi lebih kompleks,
- biaya/latency bisa lebih tinggi dibanding HTTP API untuk use case sederhana,
- deployment/stage management lebih banyak keputusan.

- HTTP routing sederhana,
- Lambda atau HTTP backend,
- lower-latency/lower-cost API surface,
- JWT authorizer umum,
- parameter mapping ringan,
- tidak membutuhkan seluruh feature REST API.

- internal product API,
- mobile/web backend API,
- simple microservice façade,
- API berbasis Lambda proxy,
- API dengan contract validation dilakukan di application layer,
- workload high-volume yang tidak membutuhkan REST API feature set penuh.

+ lebih sederhana,
+ cocok untuk sebagian besar API modern,
+ baik untuk Lambda/HTTP proxy workloads,
- tidak semua feature REST API tersedia,
- governance contract sering harus dipindahkan ke app/CI,
- jika butuh usage plans atau deep gateway modeling, REST API bisa lebih tepat.

- realtime notification,
- collaboration presence,
- chat,
- order status push,
- trading/market updates,
- operational dashboards,
- long-running workflow progress.

connection state != business state

- connection registry,
- authorization model,
- routing semantics,
- disconnect cleanup,
- fanout control,
- backpressure model,
- delivery fallback,
- replay/read model untuk client yang offline.

write business state -> publish event/outbox -> push notification -> client refreshes/read model

HTTP API by default untuk simple modern HTTP API.
REST API ketika butuh API governance feature yang spesifik.
WebSocket API ketika komunikasi dua arah adalah bagian dari product semantics.

POST /updateOrder
POST /process
POST /action
POST /orders/{id}

POST /orders
POST /orders/{id}/cancel
POST /orders/{id}/submit
POST /orders/{id}/capture-payment
GET  /orders/{id}
GET  /orders?customerId=...

POST /cases/{id}/escalate
POST /claims/{id}/approve
POST /payments/{id}/capture
POST /shipments/{id}/dispatch

- transition valid,
- precondition jelas,
- idempotency jelas,
- response jelas,
- failure behavior jelas,
- audit event jelas.

POST /generate-report
-> Lambda
-> query besar ke database
-> transform file
-> upload file
-> return response

- client bisa timeout,
- API Gateway bisa timeout,
- Lambda bisa timeout,
- database lock/query bisa lama,
- retry client bisa memulai job ganda,
- response sukses/gagal tidak jelas,
- progress tidak terlihat.

HTTP/1.1 202 Accepted
Location: /reports/rpt_01J...
Content-Type: application/json

{
  "jobId": "rpt_01J...",
  "status": "PENDING",
  "statusUrl": "/reports/rpt_01J..."
}

POST command -> return job id -> WebSocket/SSE/polling for progress

client timeout
  > API Gateway integration timeout
    > application server timeout
      > database query timeout
        > downstream service timeout

client: 10s
API Gateway: 29s
backend: 60s
database query: unlimited

client sudah pergi,
API masih menunggu,
backend masih bekerja,
database masih memegang resource,
retry client memulai request baru,
akhirnya terjadi duplicate side effect.

client: 8s
API Gateway: 7s
backend app: 6s
database statement timeout: 3s
downstream call: 1-2s

- pakai idempotency key,
- simpan command record,
- commit state secara deterministik,
- return same result saat retry,
- jangan mengandalkan client tahu apakah commit terjadi.

HTTP timeout says: client did not receive answer.
It does not say: backend did not commit.

Idempotency-Key: ordcmd_01J...

CREATE TABLE api_idempotency_record (
    tenant_id          text        NOT NULL,
    idempotency_key   text        NOT NULL,
    command_hash      text        NOT NULL,
    status            text        NOT NULL,
    response_status   integer,
    response_body     jsonb,
    created_at        timestamptz NOT NULL DEFAULT now(),
    expires_at        timestamptz NOT NULL,
    PRIMARY KEY (tenant_id, idempotency_key)
);

same idempotency key + same command hash -> return same outcome
same idempotency key + different command hash -> 409 conflict
key expires only after business-safe TTL
response is persisted only after business commit is known
external side effects also need idempotency key

cheap syntactic rejection at gateway
semantic validation in app
hard invariant in database
reconciliation for cross-system invariant

{
  "customerId": "cus_123",
  "items": [
    { "sku": "SKU-001", "quantity": 2 }
  ]
}

- customerId wajib,
- items minimal 1,
- quantity integer >= 1,
- sku string.

- customer aktif,
- SKU tersedia,
- user boleh order untuk customer,
- quantity tidak melampaui policy.

- order id unik,
- state transition valid jika dimodelkan dengan constraint,
- idempotency key unik,
- foreign key bila relational boundary memungkinkan.

- menambahkan correlation id,
- meneruskan identity claims tertentu,
- mengubah path/query/header sederhana,
- menyembunyikan backend detail,
- compatibility shim sementara,
- integrasi legacy yang tidak bisa diubah cepat.

- business rule,
- domain decision,
- database-derived computation,
- complex branching,
- workflow orchestration,
- authorization domain detail yang butuh data lookup kompleks.

API Gateway mapping template contains business logic.

- sulit di-test seperti code biasa,
- observability terbatas,
- review domain logic tersebar,
- error handling menjadi aneh,
- sulit refactor,
- debugging production lambat.

API Gateway -> Lambda -> RDS directly

- Lambda concurrency naik,
- setiap execution membuat koneksi DB,
- RDS max_connections habis,
- semua request gagal,
- retry memperburuk kondisi.

- RDS Proxy,
- connection reuse,
- concurrency limit,
- queue untuk write-heavy async work,
- statement timeout,
- bulkhead per command type,
- backpressure di API Gateway/app.

- max pool size,
- timeout query,
- slow query alert,
- readiness/liveness yang benar,
- load shedding,
- endpoint-level rate limit,
- database circuit breaker untuk non-critical query.

API Gateway -> SQS SendMessage
API Gateway -> Step Functions StartExecution
API Gateway -> EventBridge PutEvents

- request validation kuat,
- idempotency strategy ada,
- error mapping jelas,
- auth tidak hanya “boleh hit endpoint”, tetapi boleh command apa,
- schema/event envelope stabil,
- observability mencatat command id.

API Gateway allows 10k RPS
backend can handle 2k RPS
database can handle 500 write TPS

external quota <= app capacity <= database safe capacity

- throttle command endpoint lebih ketat daripada query endpoint,
- buat quota per tenant/client,
- gunakan idempotency key agar retry tidak memperbanyak write,
- pindahkan long-running mutation ke queue/workflow,
- ukur DB write latency dan lock wait sebagai scaling signal.

- cache read model,
- pakai projection,
- pakai pagination,
- batasi filter mahal,
- hindari query “contains everywhere”,
- rate-limit expensive search.

{
  "errorMessage": "org.postgresql.util.PSQLException: deadlock detected"
}

{
  "type": "https://api.example.com/problems/conflict",
  "code": "ORDER_STATE_CONFLICT",
  "message": "The order cannot be cancelled in its current state.",
  "traceId": "1-...",
  "retryable": false
}

code: stable machine-readable error code
message: safe human-readable message
traceId/requestId: support/debug reference
retryable: whether client may retry
fieldErrors: validation details when applicable

504 does not mean the command did not commit.

- requestId,
- traceId,
- route/method/resource,
- status,
- integration status,
- latency,
- integration latency,
- caller/tenant/client id,
- user agent,
- throttled count,
- 4xx/5xx count,
- authorizer error,
- validation error,
- backend timeout,
- payload size class,
- idempotency key presence for command endpoints.

{
  "requestId": "$context.requestId",
  "extendedRequestId": "$context.extendedRequestId",
  "routeKey": "$context.routeKey",
  "status": "$context.status",
  "integrationStatus": "$context.integrationStatus",
  "responseLatency": "$context.responseLatency",
  "integrationLatency": "$context.integrationLatency",
  "sourceIp": "$context.identity.sourceIp",
  "userAgent": "$context.identity.userAgent"
}

traceId
apiRequestId
idempotencyKey
commandId
tenantId
aggregateId
stateTransition
transactionId/outboxId

PK: tenantId#userId
SK: connectionId
attributes:
  - connectedAt
  - lastSeenAt
  - principal
  - channel subscriptions
  - ttl

find all connections for user
delete connection by connectionId
expire stale connection by TTL
query all connections for tenant/channel if fanout dibutuhkan

- $disconnect tidak selalu menjadi satu-satunya sumber cleanup,
- client reconnect membuat connection id baru,
- user bisa punya banyak device/tab,
- send callback bisa gagal karena connection gone,
- fanout besar bisa overload,
- push message bisa duplicate,
- offline client butuh read model/replay via HTTP query.

critical state -> durable database/read model
notification -> WebSocket best-effort push
client -> GET latest state after receiving notification

{
  "type": "ORDER_STATUS_CHANGED",
  "orderId": "ord_123",
  "version": 42
}

{
  "entireOrderObject": "...large mutable object..."
}

POST /svc/v1/legacy/doCancel?oid=123

POST /orders/123/cancel

- route rewrite,
- header normalization,
- auth context forwarding,
- simple field rename sementara,
- request envelope adaptation.

- domain policy,
- state machine transition,
- data enrichment kompleks,
- multi-step workflow,
- cross-database validation.

dev
staging
prod

- stage variable/config drift,
- deployment immutability,
- rollback strategy,
- custom domain mapping,
- canary release jika tersedia dan dibutuhkan,
- contract versioning,
- consumer migration,
- log retention per stage,
- metrics per route/stage,
- WAF/auth config parity,
- quota parity.

OpenAPI/CDK/SAM/Terraform change
-> lint
-> contract diff
-> security review
-> deploy staging
-> integration test
-> backward compatibility test
-> deploy prod
-> monitor 4xx/5xx/latency/throttle

- API Gateway validates syntactic request shape.
- Lambda validates domain rules.
- Aurora enforces unique order/idempotency constraints.
- Outbox prevents state/event split-brain.
- EventBridge is not called before DB commit.
- Client can safely retry with same idempotency key.

GET endpoint must declare freshness expectation.

- strongly consistent source read,
- eventually consistent read model,
- cached with max staleness,
- read-after-write token/version.

{
  "orderId": "ord_123",
  "status": "CONFIRMED",
  "version": 42,
  "generatedAt": "2026-07-06T09:00:00Z",
  "source": "ORDER_READ_MODEL"
}

- workflow state is durable in Step Functions/job DB,
- WebSocket is notification channel,
- client can recover by querying job status,
- missed WebSocket message does not lose business state,
- notification payload includes version/progress pointer.

GET /query?sql=...

- authorization impossible at domain level,
- query cost unbounded,
- schema leaks,
- migration impossible,
- client coupling to database,
- injection/security risk besar.

POST /execute
{
  "action": "cancelOrder",
  "payload": {...}
}

- observability per operation buruk,
- throttling per command sulit,
- auth per action tersembunyi,
- OpenAPI tidak bermakna,
- client contract tidak jelas.

{
  "success": false,
  "error": "INVALID"
}

- caches/proxies/client libraries salah interpretasi,
- monitoring 4xx/5xx tidak bekerja,
- retry policy bingung,
- API Gateway metrics kehilangan makna.

If WebSocket message sent, user has received state.

if status == A call service X else call service Y

[ ] endpoint diklasifikasikan sebagai command/query/notification
[ ] API type dipilih dengan alasan tertulis: REST/HTTP/WebSocket
[ ] OpenAPI/contract tersedia dan direview
[ ] request validation boundary jelas
[ ] domain validation ada di application layer
[ ] database invariant ada di database layer bila memungkinkan
[ ] idempotency key wajib untuk mutation yang retryable
[ ] timeout budget ditentukan end-to-end
[ ] long-running operation memakai 202 + job/workflow pattern
[ ] throttling disesuaikan dengan backend/database capacity
[ ] error response stabil dan tidak membocorkan backend
[ ] access log structured JSON
[ ] trace/correlation id masuk ke app/database/workflow log
[ ] 4xx/5xx/throttle/latency alarm ada
[ ] canary/synthetic test ada untuk critical route
[ ] rollback strategy ada
[ ] WebSocket connection registry punya cleanup dan TTL
[ ] direct AWS service integration punya schema, auth, dan DLQ/retry plan
[ ] public contract tidak expose database schema

Regulatory case management platform.
Case can be created, assigned, escalated, reviewed, closed.
Some actions trigger async notifications and SLA timers.
Some clients need realtime dashboard updates.

POST /cases
GET /cases/{caseId}
POST /cases/{caseId}/assign
POST /cases/{caseId}/escalate
POST /cases/{caseId}/close
GET /cases?status=OPEN&assignee=...
WebSocket channel: case-progress notifications

which endpoints require idempotency key?
which transitions require optimistic concurrency version?
which actions start Step Functions workflow?
which events go to EventBridge?
which queries read source DB vs projection?
which route has strictest throttle?
which errors are 409 vs 422?
what happens if API returns 504 after escalation committed?
what if WebSocket notification fails?

API Gateway is not business logic.
API Gateway is not database protection by default.
API Gateway is not workflow engine.
API Gateway is not durable event delivery.

- contract boundary,
- traffic boundary,
- auth integration point,
- validation adapter,
- integration adapter,
- observability edge,
- blast-radius control.

HTTP API untuk common modern API yang sederhana dan efisien.
REST API untuk governance dan feature-rich API product boundary.
WebSocket API untuk bidirectional/realtime notification, bukan source of truth.

command/query semantics,
state mutation risk,
timeout budget,
idempotency,
database capacity,
contract compatibility,
observability,
failure recovery.