API Design Guide: REST, Errors, Pagination and Versioning
A good API is predictable: the same ideas work the same way everywhere. This guide follows the API Design series from naming a resource to reviewing a whole API, with the security lessons that go with it.
Every example is a small server that was run, first the wrong way, then the right way.
Who it is for: Back-end and full-stack developers who design or consume APIs, and candidates for API design and system design interviews.
13 lessons · Published by Jainik · Last updated
1. The basics of a clean REST API
- 1. API Design · 12 minWhat Makes a Good API: Resources, URLs and the Contract
What an API contract is, REST in plain words, naming resources and URLs, and the rules that make an API predictable.
- 2. API Design · 14 minHTTP Methods, Status Codes and Idempotency in Practice
GET, POST, PUT, PATCH and DELETE used correctly, the status codes that matter, and why idempotency decides whether a retry is safe.
- 3. API Design · 14 minRequest and Response Design: JSON Shapes, Errors and Validation
Consistent JSON, naming, dates and money, one error format (RFC 9457 problem details), validation with clear messages, and what never to return.
2. Lists and change over time
- 4. API Design · 14 minPagination, Filtering and Sorting
Offset versus cursor pagination with real timings, stable ordering, filters, sorting, and how to return links and counts.
- 5. API Design · 13 minVersioning, Compatibility and Evolving an API
Breaking versus safe changes, URL, header and date versions, deprecation, and how to change an API without breaking clients.
3. Reliability and safety
- 6. API Design · 15 minIdempotency Keys, Retries, Webhooks and Rate Limits
Safe retries with idempotency keys, webhooks with signatures and retries, rate limit headers, and long-running jobs.
- 7. API Design · 15 minAPI Authentication and Authorization: API Keys, OAuth 2.0 and Scopes
API keys, bearer tokens, OAuth 2.0 flows in plain words, scopes, and common mistakes. Ties back to the Security series.
- 8. Security for Developers · 14 minAccess Control: IDOR, Roles and Mass Assignment
The number one web risk: checking who you are but not what you may do. IDOR with a real example, deny by default, roles and ownership checks, and mass assignment.
- 9. Security for Developers · 15 minAPIs and Servers: SSRF, File Uploads, Rate Limits and Misconfiguration
Server-side request forgery, unsafe file uploads, missing rate limits, verbose errors, CORS mistakes and the OWASP API Top 10, each with a small example and a fix.
4. Contracts, GraphQL and gRPC
- 10. API Design · 13 minDocumenting APIs: OpenAPI, Contracts and Testing
Write an OpenAPI file, generate docs, validate requests and responses against it, contract tests and mock servers.
- 11. API Design · 15 minGraphQL and gRPC: When Not to Use REST
What problems GraphQL and gRPC solve, the real costs (N+1, caching, tooling), a small working example of each, and a decision table.
5. Review and interview
- 12. API Design · 15 minAPI Design Interview Questions and Review Checklist
A checklist to review any API, and the questions interviewers ask with model answers.
- 13. Backend in Depth · 15 minValidation at the Edge: Schemas, DTOs and Trusting Nothing
Check input where it enters the API, share schemas with the frontend, and keep validation errors apart from business-rule errors.
More reading orders are on the guides page, and every series is listed on the home page.