Everything I know about good API design

Maybe I just don't understand what the word interface means other than the GUI version of it. What's an interface in the analogue world? [2]

By the way, one person downvoted me. To that person: it's fine that you downvoted me, but also let's try to keep an open and inclusive culture?

I know it's a beginner question. I'm not a beginner, I use APIs all the time and have designed them as well. Just how I used servers without knowing for 5 years the semantic meaning behind it [1]. Understanding things deeply in that way is not my forte.

[1] Though most people still don't know that clients/servers are roles of computer programs. Many programmers conflate servers with actual hardware in the sense of "a computer can be a client of a server". Well, no a piece of code can be a client to another piece of code and a server can be a piece of code to another piece of code. They're roles, not distinct hardware.

[2] Claude mentions:

Analog World Interfaces

Door handle - The interface to a door mechanism. Whether it's a simple latch or complex electronic lock, you just turn/push the handle. An interface is basically the part you touch/use without needing to understand what's behind it.

First, to contrast the "application programmer interface" (i.e. what code has to be written to use it properly in an environment with a compiler) from the "application binary interface" (i.e. what actual bytes have to be provided in order to work with an already compiled version — important for linking, inter-process communication etc.).

Second, to be able to talk about what you actually do with the headers (i.e. what the rules are for using the code) separately from the headers themselves (i.e. just the code itself), and to abstract over other programming languages that don't work the same way.

> They're roles, not distinct hardware.

So, you already understand the value of these kinds of distinctions. A shame we haven't historically made them more consistently. (As an exercise, try to list everything that "static" can mean in every programming language you know where that's a keyword. For bonus points, contrast and compare to how the word is used in the discussion of programming language design.)

> Maybe I just don't understand what the word interface means other than the GUI version of it. What's an interface in the analogue world? ... Claude mentions:

In the world that I was recalling, when people were unfamiliar with a word, they used a resource called a "dictionary" to look them up. This provided a pre-written answer directly, rather than relying on sophisticated computer models to come up with something new every time. Admittedly, this did trend towards online use over time, in particular since this made it easier to update these resources to reflect current use patterns. But those online resources are still available, e.g. https://www.merriam-webster.com/dictionary/interface .

Even with AI expanding so far as to creep into search engines, you can still reliably obtain such definitions with search queries consisting of "define" + the word.

Just as I am irritated that people seem to have forgotten that "applications" can potentially run completely locally, and that programs can be designed around the assumption that the "front end" (UI) and "back end" (business logic) will communicate directly (or at least exist within the same process, even if there are good reasons to set up message queues etc.).

But, you know, that's bad for business. Because that entails that the consumer might actually get to own something, even if it's just an ephemeral pattern of bits on local storage.