Live data from Hacker News

Everything I know about good API design

seangoedecke.com

161–168 of 168 posts

Re: Everything I know about good API design

#161
post #4

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…

If you really care about maintaining v1 long-term you'd re-implement it as a small shim above v2.

Re: Everything I know about good API design

#162
post #150

"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

But why? Now the client has strictly less information than it had before.

The client already has the capability to handle 404 for DELETEs.

Re: Everything I know about good API design

#163

Earlier 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.

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

#164

Pagination: 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…

It’s certainly been my experience that page sizes should be bigger than you initially expect. Paginated endpoints are typically iterated all the way through meaning you’re going to return that data anyway. May as well save the additional overhead from multiple requests.

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

#165

Earlier 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.

You don’t need to bake it in from the start.

Re: Everything I know about good API design

#166

API 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…

There is always an outlier, but Quickbooks is currently on minor version 75.

Re: Everything I know about good API design

#167

Earlier 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.

Afaik Postgres doesn't. In my exposure it'd be quite uncommon for a b-tree to store the size of a subtree; would cause more churn/writes when updating trees.

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

#168

In 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…

GraphQL has some impressive points, but sometimes feels like it shifts too much control to the client. I'm on the fence about it.

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.

Post reply on HN