# Exercise 1: Design the API Layer for a Public Partner API

`ShipFast` exposes a logistics API to ~300 partner companies and to its own mobile app.

Requirements:
- Partners call `POST /shipments`, `GET /shipments/{id}`, `GET /shipments/{id}/label` (PDF, up to 8 MB) and `POST /webhooks` (register a callback URL).
- Partners must be metered: Free tier 1,000 requests/day, Pro 100,000/day, burst ≤ 20 req/s per partner.
- The mobile app uses Cognito user pools (OIDC tokens); partners authenticate with OAuth2 client credentials.
- Label generation takes 5–60 seconds.
- Security team requires WAF with rate-based rules and blocking of known bad IPs.
- Backend: Lambda functions + DynamoDB; the label generator runs on ECS in private subnets.

## Deliverables

1. **HTTP API or REST API** (or both)? Decide per audience and justify with the feature table in section 2.
2. **Authentication** for partners and the mobile app; explain why API keys alone are insufficient and what role they still play.
3. **Metering**: usage plans, quotas and throttles per tier; what partners receive when they exceed limits.
4. **Label generation** within the 29-second limit: describe the asynchronous flow (status codes, polling or webhooks) and how the 8 MB PDF is delivered (hint: not through API Gateway).
5. **Private backend**: how API Gateway reaches the ECS service (VPC Link + NLB/ALB/Cloud Map).
6. **Observability**: the access-log format fields you'd require and two alarms.
7. **Draw** the request path for `GET /shipments/{id}` from a partner, naming every hop.

## Requirements Checklist

- [ ] REST API for partners (usage plans, API keys for metering, WAF, request validation) and HTTP API (JWT authorizer) for the mobile app — or one REST API with justification.
- [ ] Partners authenticate with OAuth2 client credentials (Cognito resource server / JWT or Lambda authorizer); API keys only identify/meter the partner.
- [ ] Usage plans: Free 1,000/day quota, Pro 100,000/day, per-key throttle 20 rps burst; exceeding returns 429.
- [ ] Label: `POST` returns 202 with a job id; status via polling or webhook; PDF delivered via a presigned S3 URL.
- [ ] Private integration via VPC Link to an internal NLB/ALB (or Cloud Map for HTTP APIs).
- [ ] Access logs include requestId, partner/key id, routeKey, status, latency, integrationLatency, error messages; alarms on 5xx ratio and latency/integration latency.