While the author doesn't seem to like version based APIs very much, I always recommend baking them in from the very start of your application. You cannot predict the future and chances are there will be some breaking change forced upon you by someone or something out of your control.
I don't think the author meant they don't include /v1 in the endpoint in the beginning. The point is that you should do everything to avoid having a /v2, because you would have to maintain two versions for every bug fix, which means making the same code change in two places or having extra conditional logic multiplied against any existing or new conditional logic. The code bases that support multiple versions look li…
Everything I know about good API design
161–168 of 168 posts
Re: Everything I know about good API design
#162"Think about it - if you send three DELETE comments/32 requests in a row, it won’t delete three comments. The first successful request will delete the comment with ID 32, and the remaining requests will 404 when they can’t find the already-deleted comment." Not necessarily. Many implementations return HTTP 204 for any DELETE that succeeds in the sense that the element is gone regardless if it had been there before. T…
Indeed. Extending idempotency to the response not merely the action wherever possible
The client already has the capability to handle 404 for DELETEs.
Re: Everything I know about good API design
#163Earlier quoted context omitted.
Most REST APIs don’t support that. So you don’t need versioning for APIs that already have a request type specified .
I’m not sure what you mean in the context of a discussion about how to design APIs. If you are the one designing an API, it’s up to you what you support.
Re: Everything I know about good API design
#164Pagination: do not force me to drink from a paginated coffee stir. I do not want 640 B of data in a response, and then have to send another response for the next 640 B. And often, pagination means the calls are serialized, so I'm just doing nothing but waiting for round trip latency after round trip latency for the next meager 640 B of data. Azure I'm looking at you. Many of their services do this, but Blob storage i…
Not implementing pagination at the outset can be problematic, however. If you later want to paginate data (e.g. if the size of your data grows) then it’s going to be a breaking change to implement that later. Big page sizes but with pagination can be a reasonable balance.
Re: Everything I know about good API design
#165Earlier quoted context omitted.
I’m not sure what you mean in the context of a discussion about how to design APIs. If you are the one designing an API, it’s up to you what you support.
We call that baking them in from the very start of your application, which is what you claimed this didn’t need.
Re: Everything I know about good API design
#166API versioning mostly just means things perpetually stuck at v1. You might have the intention to change things up, but you never will. Putting version numbers in a URL is a bit of a kludge. v1 is the most common version, by far, you will ever see in a url. v2 is rare. v3 is more common strangely. I don't think I've seen a v4 or v5 or higher in the wild very often. That's just not a thing. My theory is that v1 is the…
Re: Everything I know about good API design
#167Earlier quoted context omitted.
no, because it has to count the amount of matching rows preceding the offset rows to determine the offset, i.e. iterate over all preceding rows. The cursor provides a starting point for the offset so in this instance it's not necessary. https://use-the-index-luke.com/sql/partial-results/fetch-nex...
It only has to count if the index doesn't store the amounts of records in the "chunks" it manages, does it? I'm pretty sure B-trees do actually store the sizes of the subtrees.
Perhaps some of the page-level Copy-on-Write databases (LMDB?) might do this, since they have to rewrite ancestor pages anyway.
Re: Everything I know about good API design
#168In 2025, leaving GraphQL out of a discussion on modern API design is like writing about web frameworks and downplaying React. It may not be right for every use case.. but it has become foundational in many serious frontend/backend architectures, and that deserves acknowledgment. GraphQL isn’t just another protocol. It’s a paradigm shift in how we think about designing and consuming APIs. The author downplays its role…
There are performance footguns (like recursion, for which you'd have to consult your GraphQL server library for mitigations). There is often a built-in 'introspection' endpoint, which many consider a security faux-pas (to which I disagree — I think it's pretty noble, like having built-in OpenAPI docs) BUT you can easily craft a recursive query using just this endpoint that will take (some) GraphQL servers down. There are plenty of posts written on the matter and I'm sure there are mitigations, but my first exposure to GraphQL was on someone else's project (a respectable engineer who I consider very skilled) and within the first day I had noticed this intriguing structural hazard and taken the server down...
It therefore seems to be a tool that is possibly difficult to 'hold correctly'; at least people should be cautious about going in without doing their research about these things. Probably a maturity issue, but one that people ought to be aware of?
Other gripes:
It's displeasing how the HTTP status code does not correlate with the actual success response of the API, which makes typical request logging less useful.
I guess it also makes it harder to provide optimised hot paths on the server (because your client team might shift their queries around, or whatever).
In previous experience I also find that having easily-recognisable names for API endpoints (like `GET /repositories`) makes talking about them, and recognising them, easier than the more-opaque-feeling GraphQL approach.