✳flâneur — a map of the web's best reading

How to (and how not to) design REST APIs · stickfigure/blog Wiki

github.com · 3,483 words · saved by 1 readers

Hi, my name is Jeff. I've been the CTO of companies large and small, but mostly I like to write code. Have something interesting for me to work on? I'm looking. If you want to be notified of blog updates, follow the repository. In my career, I have consumed hundreds of REST APIs and produced dozens. Since I often see the same mistakes repeated in API design, I thought it might be nice to write down a set of best practices. And poke fun at a couple widely-used APIs. Much of this may be "duh", but there might be a few rules you haven't considered yet. It's an arbitrary convention, but it's well-established and I have found violations tend to be a leading indicator of "this API will have rough edges". A common mistake seems to be trying to build your relational model into your URL structure. Etsy's new API is full of this kind of thing: The {listing_id} is globally unique; there's no reason for {shop_id} to be part of the URL. Besides irritating your developers with extra clutter, it inev

How to (and how not to) design REST APIs · stickfigure/blog Wiki · GitHub Skip to content You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} stickfigure / blog Public Notifications You must be signed in to change notification settings Fork 22 Star 574 How to (and how not to) design REST APIs Jump to bottom Jeff Schnitzer edited this page May 11, 2026 · 20 revisions Oct 30, 2023 Update 2

Explore this link on the map →

related reading