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

121–130 of 168 posts

Re: Everything I know about good API design

#121

Post by nevertoolate »

BrainyZeiny wrote: post #120

In 2025, leaving GraphQL out of a discussion on modern API design is like writing about web frameworks and downplaying React. It may not be right for every use case.. but it has become foundational in many serious frontend/backend architectures, and that deserves acknowledgment. GraphQL isn’t just another protocol. It’s a paradigm shift in how we think about designing and consuming APIs. The author downplays its role…

Caching is straw-man. Complexity tends to be higher to implement a graphql backend than for e.g. type-spec => openapi backend. For the simple case the simpler solution wins imo. For the complex case it can be a toss-up, but it seems that performance and security can be a big deal-breaker for graphql, so maybe only big enterprises can afford to go down that route.

I'm not sure what you mean by the react analogy, react seems to be far more popular than graphql in their respective areas.

Re: Everything I know about good API design

#123

Post by brainzap »

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

makes me remember a Evan: we provided a migration path from 2 to 3, but so many internal changed that many plugins broke

Re: Everything I know about good API design

#125

Post by andix »

choult wrote: post #38
andix wrote: post #31

Earlier quoted context omitted.

I don't see any harm in adding versioning later. Let's say your api is /api/posts, then the next version is simply /api/v2/posts.

It's a problem downstream. Integrators weren't forced to include a version number for v1, so the rework overhead to use v2 will be higher than if it was present in your scheme to begin.

Switching to an incompatible/breaking API requires some rework anyway. The consumer of an API usually doesn't support multiple versions in parallel.

Re: Everything I know about good API design

#126

Post by andix »

pixl97 wrote: post #52
choult wrote: post #38

Earlier quoted context omitted.

It's a problem downstream. Integrators weren't forced to include a version number for v1, so the rework overhead to use v2 will be higher than if it was present in your scheme to begin.

This here, it's way easier to grep a file for /v1/ and show all the api endpoints then ensure you haven't missed something.

Edit:

^/api(/(?!v[0-9]).)?$ is v1

^/api/v2(/.)?$ is v2

It's really not an issue in any case, it just itches your brain, because is not as neat as you would like it to be.

Re: Everything I know about good API design

#127

Post by [deleted] »

teraflop wrote: post #57
delta_p_delta_x wrote: post #47

Earlier quoted context omitted.

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…

AFAIK, it's technically legal under the LGPL to statically link glibc as long as you also include a copy of the application's object code, along with instructions for how users can re-link against a different glibc if they wish. You don't need to include the source for those .o files. But I don't think I've ever seen anybody actually do this.

[deleted]

Re: Everything I know about good API design

#128

Post by rubenvanwyk »

JimDabell wrote: post #91

This is great. One thing I would add: The quality of the API is inversely correlated to how difficult it is to obtain API documentation. If you are only going to get the API documentation after signing a contract, just assume it’s dismally bad.

This. It usually also means no OpenAPI standards, which makes integration much more difficult.

Re: Everything I know about good API design

#129

Post by cxr »

loeg wrote: post #61
delta_p_delta_x wrote: post #47

Earlier quoted context omitted.

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.

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

Re: Everything I know about good API design

#130

Post by j45 »

bigiain wrote: post #65
j45 wrote: post #32

Earlier quoted context omitted.

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

COM, DCOM..
Post reply on HN