Topic hub
API Design
REST, GraphQL and gRPC, pagination, idempotency, versioning, errors and webhooks.
Lessons
- REST Controllers and Response Handling · Spring Boot: From Basics to Production
Map HTTP endpoints, return proper status codes and headers. - HTTP and REST API Design · API Architecture and Integration Design
Resources, methods, status codes and conventions for predictable REST APIs. - OpenAPI and Contract-First Development · API Architecture and Integration Design
Design the contract first, then generate docs, mocks, clients and tests. - Errors and Validation · API Architecture and Integration Design
Consistent, actionable error responses with Problem Details. - Idempotency, Retries and Concurrency Control · API Architecture and Integration Design
Make retries safe and prevent lost updates. - Pagination, Filtering and Sorting · API Architecture and Integration Design
Return large collections efficiently and predictably. - Versioning and Evolving APIs · API Architecture and Integration Design
Change APIs without breaking clients, and retire old versions gracefully. - Designing a GraphQL Schema · GraphQL in Production
Types, nullability, IDs, naming and modeling the domain for clients. - Choosing GraphQL Wisely · GraphQL in Production
Where GraphQL shines, where it hurts, and hybrid architectures. - The Contract-First Workflow · API Platform & Lifecycle
Why teams write the spec before the code, and what the workflow looks like. - Deprecation and Sunset · API Platform & Lifecycle
Retire endpoints and fields safely with headers, data and deadlines. - Versioning Strategies · API Platform & Lifecycle
URL, header, media type and date-based versioning — and avoiding versions. - HTTP Methods: Safe, Idempotent and Cacheable · REST APIs in Depth
Use GET, POST, PUT, PATCH and DELETE with their exact semantics. - Modeling Resources and URLs · REST APIs in Depth
Design nouns, collections, sub-resources and identifiers that survive change. - Pagination in Depth · REST APIs in Depth
Offset, cursor and keyset pagination, totals, and page metadata. - Error Responses with Problem Details (RFC 9457) · REST APIs in Depth
One machine-readable error format for every endpoint. - The Idempotency-Key Pattern · Idempotency & Retry-Safe Systems
How clients and servers use keys to deduplicate unsafe requests. - Screen-Shaped Responses & Aggregation · Mobile API Best Practices
Avoid waterfalls of requests by aggregating what a screen needs. - Versioning With Old Clients in the Wild · Mobile API Best Practices
Additive changes, tolerant readers and version telemetry. - Idempotent Charges & Double-Charge Prevention · Payments & Money APIs
Idempotency keys end to end — client, your API and the PSP. - Communicating Limits: Headers and 429 Responses · Rate Limiting, Quotas & Abuse Protection
Tell clients their limits and when to retry.
Decision guides
- API Gateway vs BFF vs Service Mesh
- At-Most-Once vs At-Least-Once vs Effectively-Once
- Full Sync vs Delta Sync vs CRDTs
- Hosted Checkout vs Embedded Fields vs Direct API
- Offset vs Cursor vs Keyset Pagination
- OpenAPI vs AsyncAPI vs Protobuf
- Polling vs Push vs Persistent Connections for Mobile
- Polling vs Webhooks (vs Streaming)
Cookbook recipes
- Centralize error handling in Express 5 · Node.js
- Implement rate limiting in a PHP API · PHP
- Validate JSON API input in PHP · PHP
- Rate limit a Spring Boot API with Redis · Spring Boot
- Paginate and sort safely with Spring Data · Spring Boot
- Paginate with cursors in FastAPI · FastAPI
- Verify incoming webhooks in FastAPI · FastAPI
- Support Idempotency-Key headers in FastAPI · FastAPI
- Return RFC 9457 Problem Details from FastAPI · FastAPI
- Version a FastAPI API without breaking clients · FastAPI
- Build a validated JSON API with Route Handlers · Next.js
- Paginate and filter with searchParams in Server Components · Next.js