# Revision: Cheat Sheet and Self-Check — API Design and Versioning

Source: https://www.geekswithgeeks.com/en/api-design/wrap-revision

> 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.

**Quiz:** 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
- [x] 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.

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

- [ ] Rename it and hope
- [x] 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.

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

- [ ] Offset pagination
- [x] 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.