Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Everything I know about good API design

seangoedecke.com

Post reply on HN
Print view View original

141–150 of 168 posts

Re: Everything I know about good API design

#141

Post by scott_w »

runroader wrote: post #14

I think the only thing here that I don't agree with is that internal users are just users. Yes, they may be more technical - or likely other programmers, but they're busy too. Often they're building their own thing and don't have the time or ability to deal with your API churning. If at all possible, take your time and dog-food your API before opening it up to others. Once it's opened, you're stuck and need to respec…

A big difference is you can tell internal users to update or else. It’s not free and should be reserved for good business reasons, but it can happen on a shorter time frame as you have the internal organisation to enforce it.

It’s not really an option in the same way with end users or customers, as they aren’t part of your organisation, by definition.

Re: Everything I know about good API design

#142

Post by 1718627440 »

0xbadcafebee wrote: post #50

Most people who see "API" today only think "it's a web app I send a request to, and I pass some arguments and set some headers, then check some settings from the returned headers, then parse some returned data." But "API" means "Application Programming Interface". It was originally for application programs , which were... programs with user interfaces! It comes from the 1940's originally, and wasn't referred to for m…

You are talking as if it were a thing of a past. Yet I am 20 and when I read API, only ever think of it as in API/ABI. I don't think a protocol endpoint is an API.

Re: Everything I know about good API design

#143

Post by 1718627440 »

chubot wrote: post #26
zahlman wrote: post #20

Anyone else old enough to remember when "API" also meant something that had nothing to do with sending and receiving JSON over HTTP? In some cases, you could even make something that your users would install locally, and use without needing an Internet connection.

Well it stands for “application programming interface”, so I think it is valid to apply it to in-process interfaces as well as between-process interfaces Some applications live in a single process, while others span processes and machines. There are clear differences, but also enough in common to speak of “APIs” for both

In my knowledge, there is the distinction of API vs. protocol, i.e. whether you use the foreign software through calling into it or by serializing and sending somewhere. "web APIs" seam to be the latter not the former, so I don't get why they got christened APIs.

Re: Everything I know about good API design

#144

Post by 9dev »

JimDabell wrote: post #96
pixl97 wrote: 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.

> 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 don’t really need to do that for REST APIs. If clients request application/vnd.foobar then you can always add application/vnd.foo.bar;version=2 later without planning this in advance.

Actually, there’s nothing stopping you from using a custom "Version: 2" Header in requests and responses

Re: Everything I know about good API design

#145

Post by spacechild1 »

stronglikedan wrote: post #135
spacechild1 wrote: post #118

Earlier quoted context omitted.

You are talking in past tense, but there are still many non-web APIs. Every software library has an API. I still find it incredibly annoying that the web folks have hijacked the term "API" as a short hand for "web API".

> the web folks have hijacked the term "API" as a short hand for "web API". I don't see it. API is too vague to mean one type of API, whether it's one from before the web, or a web API. As soon as there was more than one type of API, the term API became incomplete without a qualifier. Nothing was hijacked, and your sentence includes an incomplete term.

Web devs absolutely do use "API" as a synonym for "web API". I mean, the title of this very submission is "Everything I know about good API design". One could naively expect an article about API design in general, but it's only about web APIs.

Re: Everything I know about good API design

#146

Post by spixy »

JimDabell wrote: post #96
pixl97 wrote: 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.

> 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 don’t really need to do that for REST APIs. If clients request application/vnd.foobar then you can always add application/vnd.foo.bar;version=2 later without planning this in advance.

The problem is with parameters (or headers) you are still stuck with same API schema (you cannot rename it, etc).

But thanks to versions, in my job we renamed old APIs like /v1/oauthApple and /v1/oauthGoogle to /v2/login/oauth/apple and /v2/login/oauth/google, looks so much better.

Re: Everything I know about good API design

#147

Post by spixy »

achernik wrote: post #60

> How should you store the key? I’ve seen people store it in some durable, resource-specific way (e.g. as a column on the comments table), but I don’t think that’s strictly necessary. The easiest way is to put them in Redis or some similar key/value store (with the idempotency key as the key). I'm not sure how would storing a key in Redis achieve idempotency in all failure cases. What's the algorithm? Imagine a serve…

Algorithm is that the key is changed everytime after result 200 from API or page is refreshed or changed to another.

Re: Everything I know about good API design

#148

Post by spixy »

jillesvangurp wrote: post #99

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…

You can do fallback so that {no version} endpoint points to v1 endpoint (/auth/login and /v1/auth/login are the same).

That way you have versioning and also simple urls.

Re: Everything I know about good API design

#149

Post by asddubs »

Joker_vD wrote: post #133

> Instead of using OFFSET, the query becomes WHERE id > cursor ORDER BY id LIMIT 10 Wait. Surely "ORDER BY id OFFSET 20 LIMIT 10" works about the same as "WHERE id > cursor ORDER BY id LIMIT 10", if "id" is indexed?

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

Re: Everything I know about good API design

#150

Post by gbrits »

weinzierl wrote: post #114

"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
Post reply on HN