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

81–90 of 141 posts

Re: No Abstractions: our API design principle

#81

Post by alex_lav »

chowells wrote: post #4

If there's no abstraction, what's your value-add? I don't care enough to read your marketing BS to see where you claim to be special, but... If your API is doing the exact same things as an underlying service is doing, you're just a middleman extracting rents. You might find it more valuable to state your position as "carefully scoped abstractions" to make it clear what value you add.

> If there's no abstraction, what's your value-add?

But then

> I don't care enough to read

Hmmmmmm.

Re: No Abstractions: our API design principle

#82

Post by hinkley »

cpeterso wrote: post #39

This is similar to Domain-Driven Domain's "Ubiquitous Language" design pattern, making your implementation use the same real-world terminology used domain experts. https://thedomaindrivendesign.io/developing-the-ubiquitous-l...

I was introduced to this concept a good while before DDD came along, when someone opined that if the nouns and verbs in your code don't match the problem domain that's an impedance mismatch and it's going to get you into trouble some day.

It really reads like a shame response to me. People are so pathologically allergic to saying "I was wrong" or "we were wrong" that they end up pushing their metaphors around like a kid trying to rearrange their vegetables on their plate to make it look like they ate some of them.

It's also smacks of the "No defects are obvious" comment in Hoare's Turing Award speech.

Re: No Abstractions: our API design principle

#83

Post by theptip »

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. If you have to teach your users a language, make it as simple as possible.

Re: No Abstractions: our API design principle

#84

Post by eru »

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…

Compare also exokernels, and how they delegate abstraction to libraries, not the OS.

Re: No Abstractions: our API design principle

#85

Post by eru »

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?

Just say that you don't support mixing both APIs.

Re: No Abstractions: our API design principle

#86

Post by kadoban »

trevor-e wrote: post #20
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've always seen currencies multiplied by 100 to remove the need for floating point.

If you use a higher constant, 10000 or 1000000 or something, you give yourself a good amount of more fleixibility.

Re: No Abstractions: our API design principle

#87

Post by wodenokoto »

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…

But it must have _some sort_ of API. Since your rest API is modelled on their API it made me really curious about how you communicate with those networks.

Re: No Abstractions: our API design principle

#88

Post by cpeterso »

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…

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

Re: No Abstractions: our API design principle

#89

Post by tegling »

One tricky thing to model neatly in payment APIs is that payment schemes indicate the roles of payer and payee in payment returns in different ways. E.g. for one particular scheme the payer and payee may be kept in the same position as in the initial payment (creditor of payment return is actually the one sending funds) whereas in another one they are switched (creditor is the one receiving funds in the return). I'd be curious to see how they are handling this case as it can be a real head-scratcher.

Re: No Abstractions: our API design principle

#90

Post by actionfromafar »

eru wrote: post #85
lmz wrote: post #61

Earlier quoted context omitted.

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?

Just say that you don't support mixing both APIs.

That’ll fix it. ;-)
Post reply on HN