Lesson 27 / 27

Revision: Cheat Sheet and Self-Check

Review the principles, conventions and versioning practices from the whole course.

Cheat sheet

Design: consumer-first; plural-noun resources; methods carry the verb (GET/HEAD safe, PUT/DELETE idempotent, POST neither); choose REST/GraphQL/gRPC/webhooks by need. Responses: precise status codes; application/problem+json errors; cursor pagination; filter/sort/fields conventions. Reliability: Idempotency-Key for POST, ETag/If-None-Match/If-Match, rate limits with 429 + Retry-After, 202 + status resource. Security: HTTPS, header tokens, scopes, object-level authorisation (BOLA), minimal responses, signed webhooks with timestamps. Versioning: additive first; know breaking changes; URI/header/media-type/date-based; one internal model. Deprecation: Deprecation + Sunset + Link headers, long timeline, usage tracking, migration guide, 410 Gone. Quality: OpenAPI contract-first, contract and breaking-change tests, style guide and review.

Questions interviewers ask

Be ready to explain: the difference between PUT, PATCH and POST and which are idempotent, how you would design pagination for a changing dataset, how idempotency keys prevent double charges, what counts as a breaking change and how you would version and retire it, and how you would stop one user reading another user's orders.

Quick check: A mobile app retries `POST /payments` after a timeout and the customer is charged twice. What is the best fix?

  • Return 200 for every error
  • Disable retries on the client only
  • Switch the endpoint to GET
  • Require an Idempotency-Key and replay the stored result for repeats
Answer

Require an Idempotency-Key and replay the stored result for repeats — The key ties retries to one logical operation so the charge happens once.

Quick check: You must rename a response field used by thousands of clients. What is the safest plan?

  • Rename it and hope
  • Add the new field alongside the old one, deprecate the old with a sunset date and track usage
  • Remove it silently next release
  • Change its meaning but keep the name
Answer

Add the new field alongside the old one, deprecate the old with a sunset date and track usage — Additive change plus a deprecation period lets clients migrate on their own schedule.

Quick check: A client requests page 2 after rows were inserted at the front of the list. Which pagination avoids duplicates?

  • Offset pagination
  • Cursor (keyset) pagination
  • Random pagination
  • No pagination
Answer

Cursor (keyset) pagination — A cursor continues after the last seen item, regardless of inserts earlier in the list.