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

41–50 of 168 posts

Re: Everything I know about good API design

#41

Post by pixelatedindex »

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.

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.

Re: Everything I know about good API design

#42

Post by jahewson »

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?

/api/postsFinalFinalV2Copy1-2025(1)ExtraFixed

Re: Everything I know about good API design

#43

Post by wener »

I still try think /v1 /v2 is a break, I don't trust you will keep v1 forever, otherwise you'll never introduce this execuse.

I'd like to introduce more fields or flags to control the behavior as params, not asking user to change the whole base url for single new API.

Re: Everything I know about good API design

#44

Post by dfee »

mettamage wrote: post #34
drdaeman wrote: post #25

Earlier quoted context omitted.

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.

I never understood why libraries also had the word API. From my understanding a library is a set of functions specific to a certain domain, such as a statistics library, for example. Then why would you need the word API? You already know it’s a library. For end points it’s a bit different. You don’t know what are they or user facing or programmer facing. I wonder if someone has a good take on this. I’m curious to lea…

To use code, you need an interface. One for programming. Specifically to build an application.

Why does the type of I/O boundary matter?

Re: Everything I know about good API design

#45

Post by calrain »

wener wrote: post #43

I still try think /v1 /v2 is a break, I don't trust you will keep v1 forever, otherwise you'll never introduce this execuse. I'd like to introduce more fields or flags to control the behavior as params, not asking user to change the whole base url for single new API.

I like this pattern.

When an API commits to /v1 it doesn't mean it will deprecate /v1 when /v2 or /v3 come out, it just means we're committing to supporting older URI strategies and responses.

/v2 and /v3 give you that flexibility to improve without affecting existing customers.

Re: Everything I know about good API design

#46

Post by Retr0id »

delta_p_delta_x wrote: post #33
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".

Even if the kernel doesn't break userspace, GNU libc does, all the time , so the net effect is that Linux userspace is broken regardless of the kernel maintainers' efforts. Put simply, programs and libraries compiled on/for newer libc are ABI-incompatible or straight-up do not run on older libc, so everything needs to be upgraded in lockstep. It is a bit ironic and a little funny that Windows solved this problem a co…

otoh staticly-linked executables are incredibly stable - it's nice to have that option.

Re: Everything I know about good API design

#47

Post by delta_p_delta_x »

Retr0id wrote: post #46
delta_p_delta_x wrote: post #33

Earlier quoted context omitted.

Even if the kernel doesn't break userspace, GNU libc does, all the time , so the net effect is that Linux userspace is broken regardless of the kernel maintainers' efforts. Put simply, programs and libraries compiled on/for newer libc are ABI-incompatible or straight-up do not run on older libc, so everything needs to be upgraded in lockstep. It is a bit ironic and a little funny that Windows solved this problem a co…

otoh staticly-linked executables are incredibly stable - it's nice to have that option.

From what I understand, statically linking in GNU's libc.a without releasing source code is a violation of LGPL. Which would break maybe 95% of companies out there running proprietary software on Linux.

musl libc has a more permissive licence, but I hear it performs worse than GNU libc. One can hope for LLVM libc[1] so the entire toolchain would become Clang/LLVM, from the compiler driver to the C/C++ standard libraries. And then it'd be nice to whole-program-optimise from user code all the way to the libc implementation, rip through dead code, and collapse binary sizes.

[1]: https://libc.llvm.org/

Re: Everything I know about good API design

#48

Post by swagasaurus-rex »

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.

The downside to cursor based pagination is that it's hard to build a jump to page N button.

Re: Everything I know about good API design

#49

Post by paulhodge »

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.

I have to agree with the author about not adding "v1" since it's rarely useful.

What actually happens as the API grows-

First, the team extends the existing endpoints as much as possible, adding new fields/options without breaking compatibility.

Then, once they need to have backwards-incompatible operations, it's more likely that they will also want to revisit the endpoint naming too, so they'll just create new endpoints with new names. (instead of naming anything "v2").

Then, if the entire API needs to be reworked, it's more likely that the team will just decide to deprecate the entire service/API, and then launch a new and better service with a different name to replace it.

So in the end, it's really rare that any endpoints ever have "/v2" in the name. I've been in the industry 25 years and only once have I seen a service that had a "/v2" to go with its "/v1".

Re: Everything I know about good API design

#50

Post by 0xbadcafebee »

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 much else until 1990. APIs have existed for over 80 years. Books and papers have been published on the subject that are older than many of the people reading this text right now.

What might've those older APIs been like? What were they working with? What was their purpose? How did those programmers solve their problems? How might that be relevant to you?

Post reply on HN