8 guides and tools
API style and contracts
Choose API style, review REST contracts, document schemas, evolve versions, and understand where an API gateway and browser preflight behavior fit.
Learning path
API design for backend developers
A curated path through API style, REST checklists, OpenAPI contracts, schema boundaries, authentication, scopes, HTTP behavior, error contracts, pagination, retries, gateways, webhooks, and JSON tooling for maintainable backend APIs.
3 guides and tools
Responses and errors
Design status codes, stable error shapes, request IDs, and client-friendly failure behavior.
10 guides and tools
Authentication and access
Protect APIs with authentication choices, cookies vs tokens, API keys, OAuth scopes, service credentials, gateways, and clear auth failures.
- API Authentication Best Practices
- Cookie vs Token Authentication
- API Key vs OAuth Token: Practical Backend Differences
- API Key Design Best Practices for Backend APIs
- OAuth Scopes Explained
- OAuth Client Credentials Flow Explained
- Service Accounts Explained
- API Abuse Prevention Explained
- JWT Claims Explained
- API Gateway Explained
4 guides and tools
Reliability and retries
Make API retries safer with idempotency, abuse prevention, rate limits, backoff, and predictable response contracts.
8 guides and tools
Data and integrations
Handle paginated data, pagination metadata, webhook delivery, JSON contracts, schemas, and payload inspection.
Start here
Pillar guides
These articles are the strongest entry points into the API design cluster.
API Design Jan 21, 2026 5 min read
REST vs RPC: How to Choose an API Style
Compare REST and RPC API styles through resources, actions, payload design, caching, versioning, and backend team workflows.
API Design Jul 1, 2026 6 min read
REST API Design Checklist
Use this REST API design checklist to review resources, methods, status codes, errors, pagination, idempotency, versioning, auth, and OpenAPI docs.
API Design Jun 30, 2026 4 min read
PUT vs PATCH in REST APIs
Compare PUT and PATCH in REST APIs, including replacement vs partial updates, idempotency, validation, status codes, and backend implementation choices.
API Design Jun 30, 2026 4 min read
OpenAPI Explained for Backend Developers
Learn how OpenAPI describes REST APIs, including paths, operations, schemas, examples, auth, versioning, code generation, and contract review.
API Design Jul 1, 2026 5 min read
JSON Schema vs OpenAPI Schema
Compare JSON Schema and OpenAPI Schema for backend API contracts, including validation, documentation, examples, tooling, and compatibility.
API Design Mar 22, 2026 5 min read
REST API Status Codes Explained
Understand the HTTP status codes backend developers use most often in REST APIs, including 200, 201, 400, 401, 404, 409, and 500.
API Design Jun 29, 2026 4 min read
REST API Error Handling Best Practices
Learn practical REST API error handling patterns, including status codes, stable error codes, field errors, request IDs, and safe messages.
API Design Jun 28, 2026 4 min read
API Versioning Explained
Learn practical API versioning strategies, including URL versions, header versions, backward compatibility, deprecation, and migration plans.
Backend Jul 2, 2026 5 min read
CORS Preflight Explained
Learn how CORS preflight requests work, including OPTIONS handling, allowed methods, headers, credentials, caching, errors, and backend mistakes.
API Design Mar 29, 2026 6 min read
Idempotency in APIs Explained
Learn what idempotency means in API design, why retries create duplicate actions, and how idempotency keys protect backend workflows.
API Design Apr 5, 2026 5 min read
Pagination Strategies for REST APIs
Compare offset, cursor, and keyset pagination for REST APIs, including tradeoffs, response shapes, sorting, and backend performance.
API Design Jul 1, 2026 5 min read
API Pagination Metadata Best Practices
Learn how to design pagination metadata for REST APIs, including pageInfo, cursors, hasNextPage, limits, totals, links, sorting, and compatibility.
Backend Jul 2, 2026 6 min read
API Authentication Best Practices
Learn API authentication best practices, including tokens, API keys, OAuth, mTLS, sessions, gateways, rotation, scopes, errors, and logging.
Backend Jul 2, 2026 6 min read
Cookie vs Token Authentication
Compare cookie and token authentication for backend apps, including sessions, JWTs, CSRF, XSS, storage, CORS, mobile clients, and API tradeoffs.
Backend Jul 2, 2026 4 min read
OAuth Scopes Explained
Learn OAuth scopes for backend APIs, including permissions, consent, least privilege, access tokens, naming, validation, and common mistakes.
Backend Jul 2, 2026 5 min read
OAuth Client Credentials Flow Explained
Learn the OAuth client credentials flow for service-to-service APIs, including clients, secrets, scopes, tokens, rotation, and security risks.
Backend Jul 2, 2026 5 min read
Service Accounts Explained
Learn service accounts for backend systems, including machine identity, API access, least privilege, secrets, rotation, audit logs, and risks.
Backend Jul 2, 2026 5 min read
API Abuse Prevention Explained
Learn API abuse prevention for backend systems, including rate limits, authentication signals, quotas, bot patterns, logging, errors, and gateways.
API Design Jun 28, 2026 5 min read
Rate Limiting in APIs Explained
Learn how API rate limiting works, including fixed windows, sliding windows, token buckets, 429 responses, headers, and backend tradeoffs.
API Design Jun 29, 2026 4 min read
API Gateway Explained
Learn what an API gateway does in backend architecture, including routing, authentication, rate limiting, observability, and tradeoffs.
API Design Jun 29, 2026 4 min read
Webhooks Explained
Learn how webhooks work in backend systems, including event delivery, signatures, retries, idempotency, and common design mistakes.
API Design Jun 30, 2026 5 min read
Webhook Signature Verification Explained
Learn how webhook signature verification works, including HMAC headers, raw request bodies, timestamps, replay protection, secret rotation, and safe failures.
Related tools
Local tools for API design work
Use these browser-based tools while reviewing payloads, response contracts, IDs, and logs.
Available tool
HTTP Status Code Lookup
Search common HTTP status codes locally in your browser with REST API usage notes, retry guidance, and backend examples.
Open toolAvailable tool
JSON Schema Generator
Generate a starter JSON Schema from example JSON locally in your browser for API contracts, validation, tests, and documentation.
Open toolAvailable tool
JSON to TypeScript Types Generator
Generate TypeScript interfaces or type aliases from JSON locally in your browser for API responses, fixtures, and backend contracts.
Open toolAvailable tool
JSONPath Tester
Test common JSONPath expressions against JSON locally in your browser for API debugging, fixtures, logs, and documentation.
Open toolAvailable tool
JSON Pointer Resolver
Resolve RFC 6901 JSON Pointers against JSON locally in your browser for OpenAPI, JSON Schema, JSON Patch, and API debugging.
Open toolAvailable tool
UUID Generator
Generate UUID v4 values locally in your browser for request IDs, idempotency keys, database records, and test data.
Open toolAvailable tool
Unix Timestamp Converter
Convert Unix timestamps to UTC and local dates, or convert date strings to seconds and milliseconds locally in your browser.
Open toolHow to study
Design for clients, failures, and change.
Strong API design is not only endpoint naming. It is the contract clients rely on: request shape, response shape, schemas, status codes, retry behavior, pagination metadata, versioning, and integration failure modes.
Start with API style and response behavior, then move into reliability topics such as idempotency, rate limiting, retries, and webhook delivery.
For adjacent backend architecture topics, browse the System Design Learning Path.
FAQ
API design learning questions
What should I learn first in API design?
Start with REST vs RPC, a REST API design checklist, OpenAPI schemas, HTTP status codes, stable error responses, versioning, pagination, and idempotency. Those topics shape most long-lived backend APIs.
Is API design only about REST?
No. REST is common for public HTTP APIs, but RPC, gRPC, event-driven APIs, and webhooks are also useful depending on the workflow and clients.
Which API design mistakes cause the most production pain?
Unstable response shapes, unclear error codes, unsafe retries, missing idempotency, weak pagination rules, and breaking changes without migration plans are common sources of pain.
How do the API tools fit this learning path?
The tools help inspect status codes, generate schema or TypeScript drafts, resolve JSON paths, create request IDs, and debug timestamps while designing or reviewing APIs.