Sign in Get started

REST APIs in Depth · Capstone

Capstone: Review a Flawed API

Find and fix the design problems in an existing API.

Scenario

You are asked to review this API before it goes public:

  • GET /getUsers?page=1000&size=100000 returns {"success": true, "data": [...]}
  • POST /users/delete?id=7
  • GET /users/7/activate activates a user
  • Errors: 200 OK {"success": false, "message": "User not found"}
  • Dates: "created": "10/09/2026 14:00"; prices: "price": 19.99
  • Updates: PUT /users/7 with only the changed fields

Requirements

  • Identify every issue and its impact
  • Propose the corrected design
  • Prioritize fixes for launch

Constraints

  • Launch in 3 weeks
  • Existing internal clients must keep working during migration

Deliverables

  1. List the problems in this API and why each matters.
  2. Propose the corrected endpoints and a migration plan.

Draft each deliverable below before revealing the model answer and rubric.

Further reading: Zalando RESTful API Guidelines

Deliverables

List the problems in this API and why each matters.

Model answer

  1. Verbs in URLs (/getUsers, /users/delete) and state change via GET (/activate) — breaks HTTP semantics; crawlers/prefetch can activate users.
  2. Unbounded page size and deep OFFSET pagination — DoS risk and slow queries.
  3. Errors returned as 200 — breaks retries, monitoring, caches and SDKs.
  4. Ambiguous dates without timezone; floats for money — data corruption.
  5. PUT used as partial update — wipes omitted fields.
  6. Envelope with success flag duplicates HTTP status.

Rubric

A strong review explains the impact (security, reliability, client breakage), not just style. Bonus: missing auth/rate limiting, enumerable IDs, no versioning/deprecation plan.

Propose the corrected endpoints and a migration plan.

Model answer

  • GET /v1/users?limit≤100&cursor= → {"items": [], "next_cursor": ...}
  • DELETE /v1/users/{id} → 204; POST /v1/users/{id}:activate → 200
  • PATCH /v1/users/{id} with JSON Merge Patch; PUT only for full replacement
  • Problem Details errors with correct 4xx/5xx codes
  • RFC 3339 UTC timestamps; money as {amount, currency} minor units
  • Migration: ship /v1 alongside legacy routes; legacy routes return Deprecation/Sunset headers; track usage per client; remove after sunset

Rubric

Look for a realistic migration (parallel run, telemetry, deadlines) rather than a breaking big-bang change.

Open in the app to mark lessons complete, take notes and track your progress.