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

21–30 of 168 posts

Re: Everything I know about good API design

#21

Post by soulofmischief »

claw-el wrote: post #13
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.

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

A versioned API allows for you to ensure a given version has one way to do things and not 5, 4 of which are no longer supported but can't be removed. You can drop old weight without messing up legacy systems.

Re: Everything I know about good API design

#22

Post by CharlesW »

claw-el wrote: post #13
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.

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

You could, but it just radically increases complexity in comparison to "version" knob in a URI, media type, or header.

Re: Everything I know about good API design

#23

Post by nostrebored »

cyberax wrote: post #18
pixelatedindex wrote: post #8

Earlier quoted context omitted.

To add on, are they talking about access tokens or refresh tokens? It can’t be just one token, because then when it expires you have to update it manually from a portal or go through the same auth process, neither of which is good. And what time frame is “long-lived”? IME access tokens almost always have a lifetime of one week and refresh tokens anywhere from 6 months to a year.

If you're using APIs from third parties, the most typical authentication method is a static key that you stick in the "Authorization" HTTP header. OAuth flows are not at all common for server-to-server communications. In my perfect world, I would replace API keys with certificates and use mutual TLS for authentication.

In your perfect world, are you primarily the producer or consumer of the API?

I hate mTLS APIs because they often mean I need to change how my services are bundled and deployed. But to your point, if everything were mTLS I wouldn’t care.

Re: Everything I know about good API design

#24

Post by chubot »

dwattttt wrote: post #19

The reminder to "never break userspace" is good, but people never bring up the other half of that statement: "we can and will break kernel APIs without warning". It illustrates that the reminder isn't "never change an API in a way that breaks someone", it's the more nuanced "declare what's stable, and never break those".

Yeah, famously there is no stable public driver API for Linux, which I believe was the motivation for Google’s Fuschia OS

So Linux is opinionated in both directions - towards user space and toward hardware - but in the opposite way

Re: Everything I know about good API design

#25

Post by drdaeman »

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.

I believe it’s pretty common to e.g. call libraries’ and frameworks’ user- (developer-) facing interface an API, like in “Python’s logging library has a weird-looking API”, so I don’t think API had eroded to mean only networked ones.

Re: Everything I know about good API design

#26

Post by chubot »

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

Re: Everything I know about good API design

#27

Post by maxwellg »

TrueDuality wrote: post #7
cyberax wrote: post #2

> You should let people use your APIs with a long-lived API key. Sigh... I wish this were not true. It's a shame that no alternatives have emerged so far.

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.

Refresh tokens are only really required if a client is accessing an API on behalf of a user. The refresh token tracks the specific user grant, and there needs to be one refresh token per user of the client.

If a client is accessing an API on behalf of itself (which is a more natural fit for an API Key replacement) then we can use client_credentials with either client secret authentication or JWT bearer authentication instead.

Re: Everything I know about good API design

#28

Post by smj-edison »

pixelatedindex wrote: post #8
cyberax wrote: post #2

> You should let people use your APIs with a long-lived API key. Sigh... I wish this were not true. It's a shame that no alternatives have emerged so far.

To add on, are they talking about access tokens or refresh tokens? It can’t be just one token, because then when it expires you have to update it manually from a portal or go through the same auth process, neither of which is good. And what time frame is “long-lived”? IME access tokens almost always have a lifetime of one week and refresh tokens anywhere from 6 months to a year.

> Every integration with your API begins life as a simple script, and using an API key is the easiest way to get a simple script working. You want to make it as easy as possible for engineers to get started.

> ...You’re building it for a very wide cross-section of people, many of whom are not comfortable writing or reading code. If your API requires users to do anything difficult - like performing an OAuth handshake - many of those users will struggle.

Sounds like they're talking about onboarding specifically. I actually really like this idea, because I've certainly had my fair share of difficulty just trying to get the dang thing to work.

Security wise perhaps not the best, but mitigations like staging only or rate limiting seem sufficient to me.

Re: Everything I know about good API design

#29

Post by Bjartr »

claw-el wrote: post #13
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.

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

See the many "Ex" variations of many functions in the Win32 API for examples of exactly that!

Re: Everything I know about good API design

#30

Post by rogerthis »

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.

Things would come in SDKs, and docs were in MS Help .chm files.
Post reply on HN