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

71–80 of 168 posts

Re: Everything I know about good API design

#71

Post by marcosdumay »

rahkiin wrote: post #11
TrueDuality wrote: post #7

Earlier quoted context omitted.

There are other options that allow long-lived access with naturally rotating keys without OAuth and only a tiny amount of complexity increase that can be managed by a bash script. The refresh token/bearer token combo is pretty powerful and has MUCH stronger security properties than a bare API key.

If api keys do not need to ve stateless, every api key can become a refresh token with a full permission and validity lookup.

This.

The separation of a refresh cycle is an optimization done for scale. You don't need to do it if you don't need the scale. (And you need a really huge scale to hit that need.)

Re: Everything I know about good API design

#72

Post by claw-el »

pixl97 wrote: post #55
claw-el wrote: post #13

Earlier quoted context omitted.

If there is a breaking change forced upon in the future, can’t we use a different name for the function?

Discoverability. /v1/downloadFile /v2/downloadFile Is much easier to check for a v3 then /api/downloadFile /api/downloadFileOver2gb /api/downloadSignedFile Etc. Etc.

Isn’t having the name (e.g. Over2gb) easier to understand than just saying v2? This is in the situation where there is breaking changes forced upon v1/downloadFile.

Re: Everything I know about good API design

#73

Post by pixelatedindex »

cyberax wrote: post #62
pixelatedindex wrote: post #41

Earlier quoted context omitted.

IME, OAuth flows are pretty common in S2S communication. Usually these tend to be client credential based flows where you request a token exactly like you said (static key in Authorization), rather than authorized grant flows which requires a login action.

Yeah, but then there's not that much difference, is there? You can technically move the generation of the access tokens to a separate secure environment, but this drastically increases the complexity and introduces a lot of interesting failure scenarios.

I mean… is adding an OAuth layer in 2025 adding that much complexity? If you’re scripting then there’s usually some package native to the language, if you’re using postman you’ll need to generate your authn URL (or do username/passwords for client ID/secret).

If you have sensitive resources they’ll be blocked behind some authz anyway. An exception I’ve seen is access to a sandbox env, those are easily generated at the press of a button.

Re: Everything I know about good API design

#74

Post by pbreit »

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.

Disagree. Baking versioning in from the start means they will much more likely be used, which is a bad thing.

Re: Everything I know about good API design

#75

Post by canpan »

> many of your users will not be professional engineers. They may be salespeople, product managers, students, hobbyists, and so on.

This is not just true for authentication. If you work in a business setting, your APIs will be used by the most random set of users. They be able to google for how to call your api in python, but not be able to do things like converting UTC to their local time zone.

Re: Everything I know about good API design

#76

Post by pixl97 »

echelon wrote: post #67
pixl97 wrote: post #55

Earlier quoted context omitted.

Discoverability. /v1/downloadFile /v2/downloadFile Is much easier to check for a v3 then /api/downloadFile /api/downloadFileOver2gb /api/downloadSignedFile Etc. Etc.

I have only twice seen a service ever make a /v2. It's typically to declare bankruptcy on the entirety of /v1 and force eventual migration of everyone onto /v2 (if that's even possible).

I work for a company that has an older api so it's defined in the header, but we're up to v6 at this point. Very useful for changes that have happened over the years.

Re: Everything I know about good API design

#78

Post by rockwotj »

echelon wrote: post #66
swagasaurus-rex wrote: post #48

Cursor based pagination was mentioned. It has another useful feature: If items have been added between when a user loads the page and hits the next button, index based pagination will give you some already viewed items from the previous page. Cursor based pagination (using the ID of the last object on the previous page) will give you a new list of items that haven't been viewed. This is helpful for infinite scrolling…

You should make your cursors opaque so as to never reveal the size of your database. You can do some other cool stuff if they're opaque - encode additional state within the cursor itself: search parameters, warm cache / routing topology, etc.

Came here to say these same things exactly. Best write up I know on this subject: https://use-the-index-luke.com/sql/partial-results/fetch-nex...

Re: Everything I know about good API design

#79

Post by bigger_cheese »

echelon wrote: post #67
pixl97 wrote: post #55

Earlier quoted context omitted.

Discoverability. /v1/downloadFile /v2/downloadFile Is much easier to check for a v3 then /api/downloadFile /api/downloadFileOver2gb /api/downloadSignedFile Etc. Etc.

I have only twice seen a service ever make a /v2. It's typically to declare bankruptcy on the entirety of /v1 and force eventual migration of everyone onto /v2 (if that's even possible).

A lot of the Unix/Linux Syscall api has a version 2+

For example dup(), dup2(), dup3() and pipe(), pipe2() etc

LWN has an article: https://lwn.net/Articles/585415/

It talks about avoiding this by designing future APIs using a flags bitmask to allow API to be extended in future.

Re: Everything I know about good API design

#80

Post by rockwotj »

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…

Yes please don’t add another component to introduce idempotency, it will likely have weird abstraction leaking behavior or just be plain broken if you don’t understand delivery guarantees. Much better to support some kind of label or metadata with writes so a user can track progress on their end and store it alongside their existing data.
Post reply on HN