Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

No Abstractions: our API design principle

increase.com

Post reply on HN
Print view View original

61–70 of 141 posts

Re: No Abstractions: our API design principle

#61

Post by lmz »

Pxtl wrote: post #59
yen223 wrote: post #57

Earlier quoted context omitted.

It does double your API surface area, so that's the tradeoff you'll have to consider. It can be the correct decision in a lot of cases.

It doesn't double the security surface area if the abstracted API goes through the low-level API. The outer one is just chrome, and so the risks of screwing something up there is far lower. Unless you're using a trash language where even simple wrappers could buffer underrun or something.

Isn't there the issue of modifying the state enough through the low-level API such that it breaks the assumptions of the high-level one?

Re: No Abstractions: our API design principle

#63

Post by jampekka »

Karellen wrote: post #46

> If you’re building an abstraction-heavy API, be prepared to think hard before adding new features. If you’re building an abstraction-light API, commit to it and resist the temptation to add abstractions when it comes along. 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…

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

Re: No Abstractions: our API design principle

#64

Post by lolpanda »

tadfisher wrote: post #36
lolpanda wrote: post #18

for any APIs related to money, should the currency be in strings as opposed to in floats? This will prevent accidental float arithmetic in the code. I always find it tricky to work with currency in javascript.

I will be the contrarian: JSON numbers are not floating point values, they are strings of characters matching the format "-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?". You can choose to parse them however you want, and parsing libraries should provide a mechanism to decode to an arbitrary-precision value.

Good point. it's not a problem with JSON. It's just that most of the JSON libraries by default parse numbers into floats.

Re: No Abstractions: our API design principle

#65

Post by InvisibleUp »

Karellen wrote: post #46

> If you’re building an abstraction-heavy API, be prepared to think hard before adding new features. If you’re building an abstraction-light API, commit to it and resist the temptation to add abstractions when it comes along. 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…

.NET also does this a lot. Here's a recent devblog post looking at file I/O: https://devblogs.microsoft.com/dotnet/the-convenience-of-sys...

Re: No Abstractions: our API design principle

#66

Post by metalspoon »

jampekka wrote: post #63
Karellen wrote: post #46

> If you’re building an abstraction-heavy API, be prepared to think hard before adding new features. If you’re building an abstraction-light API, commit to it and resist the temptation to add abstractions when it comes along. 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…

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

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.

Re: No Abstractions: our API design principle

#67

Post by Terr_ »

cratermoon wrote: post #34

No Abstractions here really means "just use terms from the underlying system", which is a good naming principle in general. Problems inevitably arise over time when there's multiple underlying systems and they have different names for the same thing, or, arguably worse, use both use a name but for different things. In this example, what if the underlying payment providers have different models? Also, what if the Fede…

> No Abstractions here really means "just use terms from the underlying system"

Which sounds a bit like Domain Driven Design, although the "underlying system" in this case may be a bit too implementation-centered to be considered a real business domain.

To expand on that a bit: In DDD you generally defer to the names and conceptual-models the business-domain has already created. Trying to introduce your own "improved" [0] model or terms creates friction/miscommunications, adds opportunities for integration bugs, and ignores decades or even centuries of battle-tested specialized knowledge.

[0] https://xkcd.com/793/

Re: No Abstractions: our API design principle

#68

Post by compootr »

koreth1 wrote: post #55
Jtsummers wrote: post #44

Earlier quoted context omitted.

> Why do programmers always need a library between them and the API? You do know that libraries present an API, right? Very few people program on Linux or other OSes without using libc or the OS/distribution equivalent, and for good reason. Those libraries provide a degree of compatibility across hardware systems and operating systems (and even the same OS but different versions). Your question is about as sensible a…

I kind of hate the fact that the term "API" has lost its generality in the minds of a huge number of practitioners, and people now assume it refers to a set of network (usually HTTP) request and response formats. It's great that we have a succinct word to describe programmatic interfaces built on top of HTTP. It's not great that there's no longer a universally-understood word for the original more general meaning eve…

I think context has to be taken into account

people here are referring to some financial service on the internet, whose API is invoked over http

An article about some library might be viewed differently, i.e "X's API is better than Z's"...etc

Re: No Abstractions: our API design principle

#69

Post by Groxx »

Karellen wrote: post #46

> If you’re building an abstraction-heavy API, be prepared to think hard before adding new features. If you’re building an abstraction-light API, commit to it and resist the temptation to add abstractions when it comes along. 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…

I'm particularly fond of this pattern when you can implement the high level API that you want outside the library, which ensures that your low level API is sufficiently flexible and means you're dogfooding your own stuff as a user. It's far too easy to get used to the internal side of a tool you're building, and forget how people actually use it.

Re: No Abstractions: our API design principle

#70

Post by jrochkind1 »

jackflintermann wrote: post #11
koreth1 wrote: post #6

Earlier quoted context omitted.

Based on my previous experience on payment systems, there's a surprising amount of value in not having to maintain direct business relationships with the underlying payment providers. It is much, much easier to work with a company like Stripe than to work directly with Visa and MasterCard and the ACH network, and heaven help you if you're a small company that needs to do automated cross-border payments to a wide rang…

Yes, exactly, the important thing to us is that our users don't need to build an additional mental model between us and the networks we sit atop. If you know the network, we want you to be able to intuit how our API works. There's a very real difference (arguably the fundamental value-add of our company) in the transport layer, though. The actual mechanics of integrating with, say, FedACH, are a bit long to get into…

I'm curious to learn more about what your customers look like, what sorts of businesses and activities they are in. Where stripe's customers are working on products unrelated to payments, yours are working on products related to payments? I'm having trouble conceiving of examples.
Post reply on HN