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

131–140 of 168 posts

Re: Everything I know about good API design

#131

Post by rirze »

atoav wrote: post #107
deathanatos wrote: post #106

Pagination: do not force me to drink from a paginated coffee stir. I do not want 640 B of data in a response, and then have to send another response for the next 640 B. And often, pagination means the calls are serialized, so I'm just doing nothing but waiting for round trip latency after round trip latency for the next meager 640 B of data. Azure I'm looking at you. Many of their services do this, but Blob storage i…

Yeah, pagination ia a great option — maybe even a good default. But don't make it the only choice, give developers the choice to make the tradeoff between number of requests and payload size.

I'm curious, is there a backend reason to only offer pagination? Is it less work on the backend vs a user making X calls to get all the resources anyways?

Re: Everything I know about good API design

#132

Post by fanf2 »

0xbadcafebee wrote: post #50

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

> It comes from the 1940's originally

Really?! That’s amazingly early. There were barely even subroutine libraries at that time. I’d love to see an example of "Application Programming Interface" from that time.

(I don’t remember seeing the term until Microsoft started using it when talking about Windows in the 1990s; before then it was things like library functions or supervisor calls - but I didn’t have much experience at that point so I was probably missing some of the more collar-and-tie programmer lingo.)

Re: Everything I know about good API design

#134

Post by loeg »

Retr0id wrote: post #104
loeg wrote: post #61

Earlier quoted context omitted.

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.

You'd need to distribute ld.so also, otherwise you'll run into ld/libc incompatibilities.

Sure.

Re: Everything I know about good API design

#135

Post by stronglikedan »

spacechild1 wrote: post #118
0xbadcafebee wrote: post #50

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

You are talking in past tense, but there are still many non-web APIs. Every software library has an API. I still find it incredibly annoying that the web folks have hijacked the term "API" as a short hand for "web API".

> the web folks have hijacked the term "API" as a short hand for "web API".

I don't see it. API is too vague to mean one type of API, whether it's one from before the web, or a web API. As soon as there was more than one type of API, the term API became incomplete without a qualifier. Nothing was hijacked, and your sentence includes an incomplete term.

Re: Everything I know about good API design

#136

Post by cxr »

cxr wrote: post #129
loeg wrote: post #61

Earlier quoted context omitted.

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.

"GNU maximalist" is an odd choice of wording, since it would seem to imply people who are the most well-informed about the project's licenses, but anyone who thinks that distributing an LGPL library without your own app's corresponding source code is someone who flat out doesn't understand the LGPL.

A mistake in my own wording crept in here; this should have said:

> one who thinks that distributing an LGPL library without your own app's corresponding source code is forbidden is someone who flat out doesn't understand the LGPL

Re: Everything I know about good API design

#137

Post by atoav »

rirze wrote: post #131
atoav wrote: post #107

Earlier quoted context omitted.

Yeah, pagination ia a great option — maybe even a good default. But don't make it the only choice, give developers the choice to make the tradeoff between number of requests and payload size.

I'm curious, is there a backend reason to only offer pagination? Is it less work on the backend vs a user making X calls to get all the resources anyways?

From embedded experience I would say it could be benefitial to do paging only if you operate under heavy memory- or latency-constraints. But most APIs certainly are not.

Of course the should be some sort of maximum size, but I have seen APIs that return 1200 lines of text and require me to page them at 100 per request with no option to turn it off.

Re: Everything I know about good API design

#139

Post by o11c »

ben-schaaf wrote: post #108
throwaway2046 wrote: post #105

Earlier quoted context omitted.

You can find the history of API/ABI changes in glibc since 2011 in this table: https://abi-laboratory.pro/?view=timeline&l=glibc Granted it hasn't been updated since 2023, you can still see the trend with removed symbols in each version.

I looked into the changelog for 2.34, which this website claims removed 24 symbols. * 9 malloc debugging variables were removed, though their symbols actually remain for backwards compatibility they just don't do anything. * vtimes was removed, but the symbol remains for backwards compatibility Those were the only changelog entries listing removals. None of them cause linking issues. The 9 that did break backwards co…

The nastiest removal I'm aware of is `crypt`, and even in that case it's just a matter of adding the appropriate `LD_PRELOAD` if you can't relink.

Re: Everything I know about good API design

#140

Post by matheusmoreira »

chubot wrote: post #24
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

It's not just opinionation though. It's the kernel's leverage against the people who would keep their modules out of the git tree instead of contributing them. Those people literally get left behind and they are forced to pay maintainers to chase a continuously moving target. The solution to that is to contribute the code.
Post reply on HN