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

11–20 of 168 posts

Re: Everything I know about good API design

#11

Post by rahkiin »

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.

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

Re: Everything I know about good API design

#13

Post by claw-el »

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?

Re: Everything I know about good API design

#14

Post by runroader »

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 respect the "never break userspace" contract.

Re: Everything I know about good API design

#15

Post by [deleted] »

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?

[deleted]

Re: Everything I know about good API design

#16

Post by devmor »

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…

I think versioning still helps solve this problem.

There’s a lot of things you can do with internal users to prevent causing a burden though - often the most helpful one is just collaborating on the spec and making the working copy available to stakeholders. Even if it’s a living document, letting them have a frame of reference can be very helpful (as long as your office politics prevent them from causing issues for you over parts in progress they do not like.)

Re: Everything I know about good API design

#17

Post by cyberax »

I'm a bit of a different opinion on API versioning, but I can see the argument. I definitely disagree about idempotency: it's NOT optional. You don't have to require idempotency tokens for each request, but there should be an option to specify them. Stripe API clients are a good example here, they automatically generate idempotency tokens for you.

Things that's missing from this list but that were important for me at some points:

1. Deadlines. Your API should allow to specify the deadline after which the request is no longer going to matter. The API implementation can use this deadline to cancel any pending operations.

2. Closely related: backpressure and dependent services. Your API should be designed to not overload its own dependent services with useless retries. Some retries might be useful, but in general the API should quickly propagate the error status back to the callers.

3. Static stability. The system behind the API should be designed to fail static, so that it retains some functionality even if the mutating operations fail.

Re: Everything I know about good API design

#18

Post by cyberax »

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.

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.

Re: Everything I know about good API design

#19

Post by dwattttt »

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

Re: Everything I know about good API design

#20

Post by zahlman »

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