[jampekka]

This. There should be a low level API to be able to do rarer more complicated cases, and a higher level simple API for common cases built on the lower-level API.

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

[cpeterso]

My favorite quote about abstraction is from Edsger Dijkstra:

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

[MaxBarraclough]

That's a great quote. This topic turned up a couple of weeks ago in another thread. [0] The excellent talk Constraints Liberate, Liberties Constrain, by Runar Bjarnason, gets at the same point, and even uses this same Dijkstra quote. [1]

[0] https://news.ycombinator.com/item?id=40021696

[1] https://youtu.be/GqmsQeSzMdw?t=874 (this takes you right to the Dijkstra quote)

[dumbo-octopus]

It's 4 async calls, and it can be done entirely in the main thread so long as you use the async API. https://developer.mozilla.org/en-US/docs/Web/API/FileSystemW...

[jampekka]

For OPFS it's still 6 calls. And the async API doesn't support flushing writes.

https://developer.mozilla.org/en-US/docs/Web/API/File_System...

[metalspoon]

Tbf Vulkan is not intended for an endprogrammer. It is a deliberately low level standardization to allow directly control GPU hardware. The high-level approach (OpenGL) failed. The endprogrammer is supposed to use a third party middleware, not Vulkan itself.

[withinboredom]

Someone has to write that middleware…

[f1shy]

So OpenGL is a total failure! I learned something today… What should I use?

[jampekka]

Late in the game, but OpenGL was not a failure. It was written for fixed GPU hardware pipelines, for which OpenGL was perfectly suitable. And one with which one could write application code for without middleware. And it was a lot nicer API than the contemporary Direct3D, which was forced down people's throats with the usual Microsoft monopoly tactics.

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.

[wizzwizz4]

I like WebGPU: it's slightly higher-level than OpenGL, but the shader language is better. (For the actual web, use WebGL: like Wasm, WebGPU isn't actually suitable for use in websites.)