Just today I was working with the Web File System API, and e.g. just writing a string to a file requires seven function calls, most async. And this doesn't even handle errors. And has to be done in a worker, setting up of which is similar faff in itself. Similar horrors can be seen in e.g. IndexedDB, WebRTC and even plain old vanilla DOM manipulation. And things like Vulcan and DirectX and ffmpeg are even way worse.
The complexity can be largely justified to be able to handle all sorts of exotic cases, but vast majority of cases aren't these exotic ones.
API design should start first by sketching out how using the API looks for common cases, and those should be as simple as possible. E.g. the fetch API does this quite well. XMLHttpRequest definitely did not.
https://developer.mozilla.org/en-US/docs/Web/API/FileSystemS...
Edit: I've thought many a time that there should be some unified "porcelain" API for all the Web APIs. It would wrap all the (awesome) features in one coherent "standard library" wrapper, supporting at least the most common use cases. Modern browsers are very powerful and capable but a lot of this power and capability is largely unknown or underused because each API tends to have quite an idiosyncratic design and they are needlessly hard to learn and/or use.
Something like what jQuery did for DOM (but with less magic and no extra bells and whistles). E.g. node.js has somewhat coherent, but a bit outdated APIs (e.g. Promise support is spotty and inconsistent). Something like how Python strives for "pythonic" APIs (with varying success).
It started to break down with programmable shader pipelines. And got a bit weird, with most of the API being irrelevant for the programmable-pipeline hardware.
As for Vulkan, it's a very different type of API. It's a kind of hardware abstraction layer that's easier to write drivers for. You should not use Vulkan if you're not writing hardware drivers or middleware. It's an extremely verbose and cumbersome API to use for anything.
For a low level API it's probably OK to write other APIs on, although the extreme on-your-face verbosity seems a bit unnecessary. AFAIK widely used higher level APIs have failed to really materialize. Maybe WebGPU, which is still quite low level. Game engines did get Vulkan backends quite quickly, but I wouldn't call game engines APIs as they are nowadays.
So probably you should use a game engine, even if you don't need 95% of their features. Or don't want to use languages and architectures they are married with.
https://developer.mozilla.org/en-US/docs/Web/API/File_System...
”The purpose of abstraction is not to be vague, but to create a new semantic level in which one can be absolutely precise.”
If only the “A” in API stood for “abstraction”. For many APIs, it probably stands for “accreted”. :)
[0] https://news.ycombinator.com/item?id=40021696
[1] https://youtu.be/GqmsQeSzMdw?t=874 (this takes you right to the Dijkstra quote)
Unless you're using a trash language where even simple wrappers could buffer underrun or something.
Think about file permissions in Linux. Running ls just shows you gross file perms (current user, group, and global) but you can also grant access to other individual users, or even make a file immutable that still shows up as writable to ls. The high level api doesn’t know or care about the low level state except where it is relevant.
The high-level API needs to handle that case, if nothing better than having internal assertions that throw if it hits a case it's not designed to accommodate.
(also I'm annoyed with myself that I wrote buffer underrun in my first post instead of buffer overflow and now it's too late to edit).
There are high-level "porcelain" commands like branch and checkout.
And then there are low-level "plumbing" commands like commit-tree and update-ref.
[1] https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Po...
Also, to some extent, Emacs. There are thousands of functions (actually, a bit less than 10k in stock Emacs without packages, and over 46k in my Emacs) performing various low-level tasks, and much fewer commands (~3k in stock Emacs, almost 12k in my config), i.e., interactive functions, often higher-level, designed for the user.
Hopefully the top-level important concepts like "amount_due" will still reflect the correct numbers!
As an example, you can use chattr to make a file in Linux immutable. ls still shows that you have permission to write to the file, even though it will fail.
When people try to overthink the api and have it determine if you really can write to a file, people will try using the high level api first (chmod) and it won’t work because it has nothing to do with permissions.
KISS is really needed for high level APIs.
One level of API for implementation model.
And second level for mental model.
I’ve mainly worked in enterprise organisations or in startups transitioning into enterprise which is sort of where my expertise lies. I’ve never seen an API that wasn’t similar to the examples in this case.
I mean… I have… but they wouldn’t be labelled as high-abstraction api’s. If they needed a label it would be terrible APIs. Like sending table headers, column types in another full length array with a line for each column, and then the actual data/content in a third array. Even sending the html style that was used in what ever frontend, so that some data is represented as “some data” and other is represented as [“some data”, [“text-aligned”, “center”…],… . Yes, that is an actual example. Anyway I’ve never seen a high abstraction api and I feel like I’m missing out.
Or (as others have pointed out) the various `git` "porcelain" commands (checkout/add/commit/branch) compared to the primitive operations for dealing with various object types. Even just `git pull` as a combination of `git fetch` and `git merge`.
Or how a filesystem API of open/read/write/close/unlink is a very simple abstraction over block allocation and (in the old days) moving a disk head and waiting for the platter to spin under it in order to access the right sector. Not to mention the "directory" and "subdirectory" abstraction, instead of just having one giant table of inode numbers.
Edit: Or compare HTML with abstractions like "headings" and "paragraphs" to a raw typesetting language like troff or TeX.
You could always do both.
Provide a low-level abstraction-light API that allows fine control but requires deep expertise, and write a higher-level abstraction-rich API on top of it that maps to fewer simple operations for the most common use cases - which some of your clients might be implementing their own half-baked versions of anyway.
If you maintain a clean separation between the two, having both in place might mean there is less pressure to add abstractions to the low-level API, or to add warts and special-cases to the high-level API. If a client wants one of those things, it already exists - in the other API.
Bonus points for providing materials to help your clients learn how to move from one to the other. You can attract clients who do not yet have deep knowledge of payment network internals, but are looking to improve in that direction.