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

91–100 of 141 posts

Re: No Abstractions: our API design principle

#91

Post by Nevermark »

theptip wrote: post #83

This is a great example of the concept “ubiquitous language” from Domain Driven Design. Use language that your domain experts understand. If your users know about NACHA files, using other terms would mean they need to keep a mapping in their head. On the other hand, in Stripe’s case, their users are not domain experts and so it is valuable to craft an abstraction that is understandable yet hides unnecessary detail. I…

Or to put it another way, they are domain experts in the kinds of transactions they want to perform, not how transactions are implemented in the financial system.

Re: No Abstractions: our API design principle

#92

Post by GeneralMayhem »

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.

Ideally integers, but at a large multiplier.

Google's money proto [1] has units and nanos. Any competent ad-tech system will use something similar: integer number of micro-dollars, nano-dollars, etc. You want a fair amount of precision, so just tracking whole cents isn't enough, but you want that precision to be (linearly) equally distributed across the value space so that you can make intuitive guarantees about how much error can accumulate.

[1] https://github.com/googleapis/googleapis/blob/master/google/...

Re: No Abstractions: our API design principle

#93

Post by blowski »

campbel wrote: post #60
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.

Unlikely to double. The low level API exposes all capabilities, the high level API exposes a subset of those capabilities under a smaller surface. The high level API will not be as large as the low level.

This reminds me of the Kubernetes API.

Re: No Abstractions: our API design principle

#94

Post by withinboredom »

metalspoon wrote: post #66
jampekka wrote: post #63

Earlier quoted context omitted.

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.

Someone has to write that middleware…

Re: No Abstractions: our API design principle

#95

Post by withinboredom »

lmz wrote: post #61
Pxtl wrote: post #59

Earlier quoted context omitted.

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?

The high level API shouldn’t care about state. In other words, your “readers” should merely aggregate state and your “writers” should only care about subsets of state.

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.

Re: No Abstractions: our API design principle

#96

Post by lwhi »

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 like this idea a lot.

One level of API for implementation model.

And second level for mental model.

Re: No Abstractions: our API design principle

#97

Post by withinboredom »

zellyn wrote: post #78
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…

Problems can sneak in when you use the low-level API to do something to an object that can't be cleanly represented in the higher-level API. You need some kind of escape hatch, like a list of links to or ids of low-level details or a blob (Map of miscellaneous data that can hold the low-level additions. Hopefully the top-level important concepts like "amount_due" will still reflect the correct numbers!

Those problems usually present themselves by people overthinking the high level api and trying to be smart.

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.

Re: No Abstractions: our API design principle

#99

Post by devjab »

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 genuinely curious as to what an abstraction-rich api would look like and why it would be useful.

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.

Re: No Abstractions: our API design principle

#100

Post by int_19h »

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.

Regardless of what the libraries should be doing, there is the reality of what they are doing.
Post reply on HN