APIs
Designing and consuming APIs: REST conventions, authentication, rate limits, webhooks, OpenAPI breaking changes and MCP transports.
Intermediate
7 guidesREST API design principles: URLs, methods and errors
How REST APIs name resources, use HTTP methods safely, return status codes and RFC 9457 errors, stay stateless, paginate results and handle versioning.
API rate limiting: algorithms, 429 and Retry-After
Why APIs limit request rates, how fixed window, sliding window, token bucket and leaky bucket compare, and how clients should handle 429 and Retry-After.
Webhooks explained: signatures, retries and idempotency
How webhooks deliver events over HTTP, how to verify HMAC signatures and block replays, and how to handle retries, duplicates and the choice versus polling.
OpenAPI breaking changes: what breaks API clients
Which OpenAPI contract changes break existing clients, from removed fields to new security requirements, which are usually safe, and how to ship a break.
How enum changes break API clients and generated SDKs
Adding an enum value can break clients that read it, and removing one breaks clients that send it. Why generated SDKs fail and how to plan for new values.
OpenAPI 3.0 vs 3.1: differences and migration checklist
What changed in OpenAPI 3.1, from JSON Schema 2020-12 compatibility and type arrays to webhooks, plus a checklist for migrating a 3.0 document.
MCP stdio vs Streamable HTTP: transport security compared
How MCP's stdio and Streamable HTTP transports differ, the main risks of each, from unpinned npx packages to DNS rebinding, and how to choose between them.
Advanced
2 guidesAPI authentication: API keys vs OAuth 2.0 vs JWT
API keys identify an app, OAuth 2.0 issues scoped tokens, and a JWT is a token format. When to use each, how to validate a JWT, and where to store tokens.
Request vs response schema compatibility in APIs
Why tightening a request schema breaks clients while tightening a response is usually safe, with examples for required fields, nulls, enums and types.
Tools for this topic
Try what these guides describe on your own URLs, domains, code or files.
Turn a cURL example from API documentation into request code in the language you use.
Check code for API keys, tokens and private keys written into the source before you commit or share it.
Compare two versions of an OpenAPI 3.0 or 3.1 spec, see breaking and non-breaking changes, and export a Markdown or JSON report.