Internet / external client
  -> API Gateway public endpoint
  -> private integration
  -> private ALB/NLB/Cloud Map/service
  -> ECS/EKS/EC2/internal service
  -> database/cache/event layer

- menjaga backend tetap private,
- memisahkan external API contract dari internal service topology,
- menerapkan authorization/throttling/logging di edge API boundary,
- menghindari direct exposure ke load balancer/service,
- memberi migration layer untuk backend implementation,
- mempertahankan operational isolation antara client-facing API dan internal runtime.

API Gateway is the external API control plane.
VPC Link is the managed network bridge.
ALB/NLB/Cloud Map is the private service entry point.
The backend service remains private.

Client tidak tahu IP/service internal.
Client hanya tahu API contract.
API Gateway tidak harus membuat backend public.
Backend tetap berada di private subnet/security boundary.

Public API = contract yang dilihat client.
Private backend = implementasi internal untuk memenuhi contract.

- route/method/path,
- authentication/authorization integration,
- throttling/quota,
- request validation/mapping,
- access logs,
- custom domain/stage,
- WAF/front-door policy bila digunakan,
- client-facing error shape.

- business command/query handling,
- transaction boundary,
- database consistency,
- domain validation,
- idempotency,
- internal observability,
- downstream integration.

- backend harus tetap private dalam VPC,
- backend berjalan di ECS/EKS/EC2/private ALB/NLB,
- API Gateway tetap diperlukan untuk public API management,
- ingin migrasi backend tanpa mengubah client contract,
- ingin central edge throttling/auth/logging,
- internal service tidak boleh terekspos dengan public load balancer,
- compliance/security boundary melarang public service endpoint,
- API Gateway menjadi facade untuk beberapa private service.

- backend adalah Lambda public integration yang cukup,
- API hanya internal dalam VPC dan tidak butuh API Gateway,
- service-to-service internal traffic lebih cocok via service mesh/private ALB/Cloud Map,
- client adalah worker/event consumer, bukan external HTTP client,
- latency overhead API Gateway tidak sepadan dengan value API management.

"Private integration berarti lebih aman."

Private integration mengurangi public exposure backend, tetapi security tetap bergantung pada authn/authz, resource policy, security group, IAM, TLS, logging, secret handling, and least privilege.

Choose HTTP API when its feature set satisfies your contract and operational needs.
Choose REST API when you require REST API-specific capabilities.

- VPC Link creation/update can take time.
- It consumes networking resources in selected subnets.
- Security groups/subnets matter for reachability.
- Routing to backend is still via load balancer/listener/service discovery integration.
- Deleting VPC Link may be blocked if integrations still reference it.

Treat VPC Link as production infrastructure, not just an API setting.

- backend is HTTP/HTTPS service,
- path-based routing needed,
- host-based routing needed,
- ECS/EKS/EC2 web app behind ALB,
- want L7 health checks/routing,
- multiple services share one internal ALB carefully.

- ALB rules become hidden API routing layer,
- path rewriting mismatch with API Gateway stage/path,
- health check green does not mean business dependency healthy,
- security group path must allow traffic from VPC Link ENIs.

- L4 TCP/TLS behavior needed,
- static performance characteristics desired,
- legacy REST VPC link patterns require NLB,
- backend is not purely L7 HTTP-routed.

- less L7 routing intelligence,
- backend must handle protocol details,
- troubleshooting may require lower-level network thinking.

- service discovery is canonical,
- avoid shared load balancer rule explosion,
- service topology is dynamic,
- internal service registry is already disciplined.

- harder for teams without service-discovery maturity,
- observability path must be explicit,
- operational behavior differs from ALB/NLB.

Client calls:
  https://api.example.com/prod/orders/123

Backend might receive:
  /prod/orders/123

But backend expects:
  /orders/123

- configure parameter mapping/path override,
- make backend aware of base path,
- use custom domain/base path mapping carefully,
- use greedy proxy only when backend contract is stable,
- document route transformation in API ADR.

"It works in dev because backend tolerated both paths."

ANY /{proxy+} -> private ALB

- fast migration,
- minimal route config,
- backend controls routing,
- useful for strangler facade.

- API Gateway loses contract clarity,
- weak request validation,
- harder per-route throttling/auth,
- backend accidentally exposes internal endpoint,
- observability less precise,
- OpenAPI contract may become fiction.

POST /orders -> order service
GET /orders/{id} -> order service
POST /cases/{id}/approve -> case service

- API contract explicit,
- per-route auth/throttling/logging,
- easier deprecation/versioning,
- safer public surface,
- better observability.

- more API Gateway config,
- more IaC discipline,
- mapping complexity if backend routes differ.

Use greedy proxy for controlled migration, not as permanent public API design unless intentionally accepted.

[ ] Backend load balancer is internal, not internet-facing.
[ ] Backend service does not trust API Gateway blindly unless network/auth boundary is proven.
[ ] Authorization decision is enforced at API layer and/or service layer based on risk.
[ ] Security groups allow only required traffic.
[ ] Route-level auth matches business sensitivity.
[ ] Internal admin/debug endpoints are not reachable through greedy proxy.
[ ] Logs do not leak secrets/tokens/PII.
[ ] TLS requirement is explicit between API Gateway and backend if needed.
[ ] Resource policy/custom domain/WAF strategy is documented.

Network privacy is not authorization.

- authenticated subject,
- tenant/org,
- roles/scopes,
- correlation id,
- request id,
- source IP/user agent if needed,
- idempotency key,
- trace context.

Client header -> API Gateway validates/authenticates -> API Gateway/service creates trusted context -> backend uses trusted context.

X-Correlation-Id: generated or propagated
X-Request-Id: API Gateway request id
X-Authenticated-Subject: derived from authorizer claims
X-Tenant-Id: derived/validated, not blindly copied
X-Idempotency-Key: validated command key
traceparent: OpenTelemetry trace context

Reject privileged identity headers unless request came through trusted path and signature/context is verifiable.

client timeout
  > API Gateway timeout
    > load balancer idle timeout / target response budget
      > backend handler timeout
        > database timeout
          > downstream timeout

Client timeout:              10s
API Gateway integration:      8s
Backend request timeout:      7s
DB statement timeout:         2s
External dependency timeout:  1s each with budget

API Gateway timeout: 8s
Backend DB query:    30s
DB pool acquire:     unlimited

API returns timeout while backend keeps working.
Client retries.
Backend duplicate pressure increases.
Database remains saturated.

The inner timeout must usually be shorter than the outer timeout, and mutation endpoints must be idempotent.

GET /health -> 200

- acquire DB connection,
- write to primary database,
- publish outbox,
- read required secrets,
- access cache,
- call dependency,
- satisfy command latency.

/health/live
  - process is alive,
  - should not depend on DB deeply.

/health/ready
  - ready to serve traffic,
  - checks critical dependencies lightly.

/health/deep
  - diagnostic only,
  - not necessarily LB health check,
  - may be used by runbooks.

- request id,
- route key,
- integration status,
- response status,
- integration latency,
- authorizer latency,
- client error count,
- server error count,
- throttled requests,
- stage/deployment id,
- source identity where safe.

- target response time,
- target 5xx,
- LB 5xx,
- healthy host count,
- request count,
- rejected connection count,
- target connection error count.

- route handler latency,
- database latency,
- DB pool acquire latency,
- command success/conflict/failure,
- idempotency duplicate rate,
- dependency timeout,
- error code, not just exception class.

- API Gateway request id,
- correlation id,
- trace id,
- backend request id,
- command id,
- tenant id,
- aggregate id where safe.

Client sees 504.
API Gateway logs integration timeout.
ALB logs 200 after 11 seconds.
Backend logs DB pool wait 9 seconds.
Database logs lock wait.

POST /cases/{caseId}/approve

POST /internal/v2/workflow/case-approval-commands

- normalize paths,
- inject request context,
- hide internal route names,
- transform legacy shapes,
- preserve backward compatibility,
- allow backend migration from monolith to service.

all business transformations hidden in mapping templates

API Gateway handles protocol/contract edge concerns.
Backend handles business semantics.

API Gateway -> VPC Link -> internal ALB -> monolith

API Gateway route /orders/* -> monolith
API Gateway route /cases/* -> new case service
API Gateway route /documents/* -> document service

API Gateway exposes stable public contract.
Internal service topology can evolve behind it.

- route ownership unclear,
- duplicate auth logic,
- shared database remains hidden coupling,
- monolith endpoint accidentally remains exposed,
- contract tests missing.

- route ownership registry,
- ADR per migrated route,
- consumer contract tests,
- deprecation dates,
- dashboard per route/backend target,
- rollback route switch plan.

/internal/reindex
/internal/replay-events
/admin/reset-cache
/debug/env
/actuator
/metrics

- explicit API Gateway routes,
- backend service requires internal auth for admin paths,
- ALB listener rules separate public-route target group from admin-route target group,
- security group/subnet separation,
- route tests that assert forbidden paths are not reachable,
- WAF rules where applicable,
- no debug endpoints in production public path.

Never rely on obscurity of path names for internal API protection.

[ ] Tenant id is derived from authenticated context, not only request body.
[ ] API Gateway authorizer validates tenant access where possible.
[ ] Backend revalidates tenant ownership before database access.
[ ] Logs include tenant id safely for operations.
[ ] Throttling can protect tenant noisy neighbor scenarios.
[ ] Rate limit and quota policy are tenant-aware when needed.
[ ] Backend database query always includes tenant boundary.
[ ] Internal headers cannot be spoofed by direct backend access.

1. Provision backend service/load balancer target.
2. Validate health checks.
3. Create/update VPC Link if needed.
4. Create route/integration in non-prod.
5. Run contract tests through API Gateway endpoint.
6. Run negative tests for forbidden paths.
7. Deploy stage/canary.
8. Watch API Gateway + ALB + backend metrics.
9. Promote traffic gradually if routing supports it.
10. Keep rollback mapping ready.

- revert API Gateway route integration,
- shift ALB target group traffic,
- rollback backend deployment,
- disable new route,
- return 503 with safe retry-after for non-critical endpoint,
- route back to monolith in strangler migration.

- API Gateway API,
- stage/deployment,
- routes/methods,
- authorizer,
- integration,
- VPC Link,
- internal ALB/NLB,
- listener/rules,
- target groups,
- ECS/EKS/EC2 service,
- security groups,
- log groups,
- metrics/alarms,
- custom domain/base path mapping.

ApiGatewayHttpApi
  Route: POST /cases/{caseId}/approve
  Integration: private ALB listener via VPC Link
  Authorizer: JWT/Lambda/IAM as needed
  AccessLog: structured JSON

VpcLink
  Subnets: private subnets
  SecurityGroups: allow API Gateway ENI -> ALB listener

InternalALB
  Scheme: internal
  Listener: HTTPS/HTTP
  TargetGroup: case-service

ECSService
  DesiredCount: N
  HealthCheckGracePeriod: ...
  SecurityGroup: allow ALB -> service

- ALB scheme is internal,
- route requires authorizer,
- access logging enabled,
- no wildcard route unless approved,
- VPC Link subnets are private,
- security group ingress is minimal,
- forbidden paths absent,
- timeout settings match standard,
- alarms exist.

- 5xx rate high,
- 4xx spike unexpected,
- integration latency p95/p99 high,
- throttling spike,
- authorizer errors,
- route-specific failure.

- healthy host count below threshold,
- target 5xx high,
- target response time high,
- rejected/connection errors,
- target group no healthy targets.

- DB pool saturation,
- command p99 high,
- dependency timeout high,
- CPU/memory saturation,
- error budget burn,
- outbox stuck if endpoint writes state.

- public API route through API Gateway,
- auth-required route rejects anonymous,
- forbidden internal path inaccessible,
- mutation endpoint idempotency works,
- backend health visible internally.

- integration URI/listener correct,
- ALB/NLB target healthy,
- backend returns valid HTTP response,
- TLS/SNI/cert mismatch,
- path mapping correct,
- backend closed connection early,
- response exceeded protocol expectation.

- integration latency,
- backend request duration,
- ALB target response time,
- DB pool acquire latency,
- lock wait/deadlock,
- slow downstream dependency,
- timeout budget mismatch.

- VPC Link status,
- subnets/security groups,
- listener port/protocol,
- ALB/NLB target group,
- path stage forwarding,
- host header expectation,
- backend auth expecting different header.

- route authorizer missing,
- greedy proxy exposed internal path,
- backend trusts spoofable header,
- direct ALB access possible,
- admin endpoint lacks service-level auth,
- custom domain/base path mismatch.

[ ] Is the backend load balancer internal?
[ ] Why do we need API Gateway instead of direct internal service route?
[ ] Why do we need private integration instead of Lambda integration?
[ ] Which API type is selected and why?
[ ] Which features require REST API or HTTP API?
[ ] What is the VPC Link lifecycle owner?
[ ] What subnets/security groups are used?
[ ] What backend target is used: ALB, NLB, Cloud Map?
[ ] Are routes explicit or greedy proxy?
[ ] If greedy proxy, what prevents admin/internal endpoint exposure?
[ ] Is path/stage mapping tested?
[ ] Is identity context trusted and protected from spoofing?
[ ] Are backend services still performing authorization where required?
[ ] Are API Gateway, ALB, backend, and DB logs correlated?
[ ] Are timeout budgets aligned?
[ ] What happens when backend is slow but still processing?
[ ] Is mutation endpoint idempotent?
[ ] Are 502/504 playbooks ready?
[ ] Are canary checks deployed?
[ ] Is rollback route mapping tested?

External clients call public compliance case API.
Case service runs on ECS Fargate in private subnets.
Database is Aurora PostgreSQL private.
Service must not expose public load balancer.

POST /cases
GET /cases/{caseId}
POST /cases/{caseId}/approve
POST /cases/{caseId}/escalate
GET /cases/{caseId}/timeline

ANY /{proxy+}

- authorizer on every sensitive route,
- backend revalidates tenant/case ownership,
- idempotency key required on mutation routes,
- structured access logs,
- ALB internal only,
- forbidden path synthetic test for /admin, /debug, /actuator,
- outbox alarm for state-changing commands.

Client -> API Gateway -> public ALB -> backend

API Gateway -> VPC Link -> internal ALB

ANY /{proxy+} -> monolith

- accidental exposure,
- no clear external contract,
- weak throttling/auth granularity,
- impossible API lifecycle management.

X-User-Id: admin

API timeout: 8s
backend keeps processing mutation for 60s
client retries every 8s

duplicate pressure + ambiguous state + database saturation

- liveness endpoint for process,
- readiness endpoint for traffic,
- deep diagnostics for runbook.

- duplicate mutation,
- ambiguous commit,
- transaction isolation,
- outbox publish failure,
- cache staleness,
- stale read model,
- cross-service consistency,
- tenant authorization,
- schema compatibility.

API Gateway private integration protects backend exposure.
API-to-database transaction boundary protects business correctness.

- API Gateway remains the public API control plane.
- Backend service can stay private in VPC.
- VPC Link is managed network bridge, not an auth system.
- Explicit routes are safer than permanent greedy proxy.
- REST API vs HTTP API should be chosen by feature/contract needs.
- ALB/NLB/Cloud Map choice affects routing and operations.
- Path/stage mapping must be tested.
- Identity headers must be trusted, derived, and protected.
- Timeout budgets must align across API Gateway, load balancer, backend, and database.
- Observability must correlate API Gateway, LB, backend, and DB.
- Internal/admin endpoints must not leak through public API surface.