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

61–70 of 168 posts

Re: Everything I know about good API design

#61

Post by loeg »

delta_p_delta_x wrote: post #47
Retr0id wrote: post #46

Earlier quoted context omitted.

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 librar…

You can (equivalently) distribute some specific libc.so with your application. I don't think anyone other than GNU maximalists believes this infects your application with the (L)GPL.

Re: Everything I know about good API design

#62

Post by cyberax »

pixelatedindex wrote: post #41
cyberax wrote: post #18

Earlier quoted context omitted.

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.

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.

Re: Everything I know about good API design

#63

Post by gitremote »

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 don't think the author meant they don't include /v1 in the endpoint in the beginning. The point is that you should do everything to avoid having a /v2, because you would have to maintain two versions for every bug fix, which means making the same code change in two places or having extra conditional logic multiplied against any existing or new conditional logic. The code bases that support multiple versions look like spaghetti code, and it usually means that /v1 was not designed with future compatibility in mind.

Re: Everything I know about good API design

#64

Post by Supermancho »

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…

With internal users, you likely have instrumentation that allows you to contact and have those users migrate. You can actually sunset api versions, making API versioning an attractive solution. I've both participated in API versioning and observed it employed in organizations that don't use it by default as a matter of utility.

Re: Everything I know about good API design

#65

Post by bigiain »

j45 wrote: post #32
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.

APIs are for providing accessibility - to provide access to interactions and data inside an application from the outside. The format and protocol of communication was never fixed. In addition to the rest api’s of today, soap, wsdl, web sockets could all can deliver some form of API.

CORBA

Shudder...

Re: Everything I know about good API design

#66

Post by echelon »

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.

Re: Everything I know about good API design

#67

Post by echelon »

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.

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

Re: Everything I know about good API design

#68

Post by rcxdude »

delta_p_delta_x wrote: post #47
Retr0id wrote: post #46

Earlier quoted context omitted.

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 librar…

Musl is probably the better choice for static linking anyway, GNU libc relies on dynamic linking for a few important features.

Re: Everything I know about good API design

#69

Post by resonious »

delta_p_delta_x wrote: post #47
Retr0id wrote: post #46

Earlier quoted context omitted.

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 librar…

The Windows redistributables are so annoying as a user. I remember countless times applications used to ask me to visit the official Microsoft page for downloading them, and it was quite hard to find the right buttons to press to get the thing. Felt like offloading the burden to the users.

Re: Everything I know about good API design

#70

Post by rcxdude »

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…

GNU libc has pretty good backwards compatibility, though, so if not you want to run on a broad range of versions, link against as old a version of libc as is practical (which does take some effort, annoyingly). It tends to be things like GUI libraries and such which are a bigger PITA, because they do break compatibility and the old versions stop being shipped in distros, and shipping them all with your app can still run into protocol compatibility issues.
Post reply on HN