Bad APIs create support tickets. Good APIs create fans. Here’s how to design APIs that developers will actually enjoy using. The Fundamentals Use Nouns, Not Verbs # P G P # P G D O E O O E E B S T S G S T L a T T o T E d o T g / d u E c e d u s r t e s e / e U l e r u a s e r s s t e t s e e r e r U s U s s s / e e 1 r r 2 / 3 1 2 3 The HTTP method IS the verb. The URL is the noun. ...
You shipped v1 of your API. Users integrated it. Now you need breaking changes. How do you evolve without breaking everyone? API versioning seems simple until you actually do it. Here’s what works, what doesn’t, and how to pick the right strategy. The Core Problem APIs are contracts. When you change the response format, rename fields, or alter behavior, you break that contract. Clients built against v1 stop working when you ship v2. ...
You shipped v1 of your API. Clients integrated. Now you need to make breaking changes. How do you evolve without breaking everyone? API versioning is the answer—but there’s no single “right” approach. Let’s examine the tradeoffs. What Counts as a Breaking Change? Before versioning, understand what actually breaks clients: Breaking changes: Removing a field from responses Removing an endpoint Changing a field’s type ("price": "19.99" → "price": 19.99) Renaming a field Changing required request parameters Changing authentication methods Non-breaking changes: ...
Your API will change. How you handle that change determines whether clients curse your name or barely notice. The Three Approaches 1. URL Path Versioning G G E E T T v 1 2 / / u u s s e e r r s s / / 1 1 2 2 3 3 Pros: ...
Your API will change. Features will be added, mistakes will be corrected, and sometimes you’ll need to break things. The question isn’t whether to version — it’s how. Why Version? Breaking changes are changes that make existing clients fail: Removing a field from a response Changing a field’s type (string → integer) Requiring a new parameter Changing the meaning of a value Removing an endpoint Without versioning, every change risks breaking someone’s integration. With versioning, you can evolve the API while giving clients time to adapt. ...
Every API eventually needs to return more data than fits in a single response. How you handle that pagination affects performance, reliability, and developer experience. Let’s look at the common patterns, their tradeoffs, and when to use each. The Three Main Approaches 1. Offset Pagination The classic approach: skip N records, return M records. G G G E E E T T T / / / a a a p p p i i i / / / i i i t t t e e e m m m s s s ? ? ? o o o f f f f f f s s s e e e t t t = = = 0 2 4 & 0 0 l & & i l l m i i i m m t i i = t t 2 = = 0 2 2 0 0 # # # P P P a a a g g g e e e 1 2 3 Implementation: ...
A well-designed API feels obvious. Endpoints are predictable, responses are consistent, errors are helpful. A poorly designed API creates confusion, support tickets, and workarounds. These conventions create APIs that are intuitive to integrate. Resource Naming Use nouns, not verbs. Plural for collections: ✅ G G P P D ❌ G P G P E E O U E E O E O G T T S T L B T S T S o T E a T T o T d d E : : / / / / / / / / / u u u u u g c u u s s s s s e r s s e e e e e t e e e r r r r r U a r r s s s s s s t / s / / / e e 1 / 1 1 1 r U 2 1 2 2 2 s s 3 2 3 3 3 e 3 r / d e l e t # # # # # e L G C U D i e r p e s t e d l t a a e u t t t u s e e e s e e r u u u r s s s s 1 e e e 2 r r r 3 1 1 2 2 3 3 Nested resources for relationships: ...
Every API eventually needs to change in ways that break existing clients. The question isn’t whether to version — it’s how to version in a way that doesn’t make your users hate you. Here’s what actually works, with real trade-offs. The Three Schools of Versioning URL Path Versioning G G E E T T / / a a p p i i / / v 1 2 / / u u s s e e r r s s / / 1 1 2 2 3 3 Pros: ...
APIs are contracts. Breaking changes break trust. But APIs must evolve—new features, better designs, deprecated endpoints. The question isn’t whether to change, but how to change without leaving clients stranded. Why Versioning Matters Without versioning, you have two bad options: Never change: Your API calcifies, accumulating cruft forever Change freely: Clients break unexpectedly, trust erodes Versioning gives you a third path: evolve deliberately, with clear communication and migration windows. Versioning Strategies URL Path Versioning The most explicit approach—version in the URL: ...
Learn how to design idempotent APIs that handle duplicate requests safely, making your systems more resilient to network failures and client retries.