Twelve practical API design techniques

APIs are one of those things that look easy right up until real traffic hits them. A demo endpoint can feel “done” in an afternoon. A production API is different — it has to survive bad clients, retries, breaking changes, huge result sets, and attackers. That’s why the useful API design advice isn’t flashy. It’s the boring stuff that keeps systems standing up. ### What’s the actual idea here? The big takeaway is simple: good API design is a bundle of small, practical decisions. Not one grand pattern. Microsoft’s API design guidance leans on resource-based URLs, standard HTTP methods, statelessness, and loose coupling so clients and servers can evolve independently. Swagger’s OpenAPI spec adds the machine-readable contract layer, which turns an API from tribal knowledge into something tools can validate, document, and generate against. ### Why do people keep starting with URLs? Because the URL is the first promise you make. If endpoints are named around resources — `/users`, `/orders/123` — developers can guess how the API works before reading docs. Postman makes the same point very directly: use nouns, not verbs, and let HTTP methods carry the action. That sounds cosmetic, but it reduces confusion everywhere else. A weird URL shape usually means the model underneath is weird too. (learn.microsoft.com) ### Why do HTTP verbs matter so much? Because predictability is half the product. `GET` should read, `POST` should create, `PUT` and `PATCH` should update in distinct ways, and `DELETE` should delete. When teams improvise here, clients end up needing custom logic for every endpoint. Microsoft frames the REST interface around standard verbs for exactly this reason — loose coupling only works if both sides share the same semantics. (blog.postman.com) ### Why is versioning always on the list? Because change is guaranteed. The question is whether you break clients when it happens. Postman explicitly says to plan versioning from the start, not after the first painful migration. Basically, versioning is change management for APIs. It gives you room to improve the service without forcing every consumer to rewrite on your schedule. (learn.microsoft.com) ### Why do pagination and rate limits travel together? Because both are really about resource control. Pagination stops one request from trying to pull an entire database table over the wire. Rate limiting stops one client — or one bot — from monopolizing the system. OWASP’s API Security project treats unrestricted resource consumption as a real security category, not just a performance nuisance. That’s the important shift — these are reliability features and abuse-prevention features at the same time. (blog.postman.com) ### What about errors? Bad APIs make you reverse-engineer failures from random strings. Good APIs return consistent error shapes and meaningful HTTP status codes. Postman calls this out because debugging time compounds fast when every endpoint fails differently. Standard errors are one of those unglamorous decisions that massively improve developer experience. ### Why are idempotency and retries such a big deal? (owasp.org) Because networks fail all the time. Clients retry. Proxies retry. Humans mash buttons twice. If a repeated request creates duplicate payments or duplicate orders, the API is fragile. Postman highlights idempotency as a design goal for exactly that reason — retries should be safe where they can be safe. ### Where does documentation fit? (blog.postman.com) At the center, turns out. OpenAPI matters because it makes the contract explicit. Humans can read it, but tools can also generate docs, clients, tests, and validation from it. That changes documentation from a side project into part of the API itself. ### Bottom line? The “12 techniques” framing is useful because it reminds people that API quality is cumulative. (blog.postman.com) Versioning, pagination, rate limits, standard errors, auth, idempotency, and clear contracts are not extras. They’re the difference between an API that works in a tutorial and one that survives production. (swagger.io)