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

51–60 of 141 posts

Re: No Abstractions: our API design principle

#51

Post by paulddraper »

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…

Git is an example of this. [1]

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

Re: No Abstractions: our API design principle

#52

Post by [deleted] »

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…

[deleted]

Re: No Abstractions: our API design principle

#53

Post by koreth1 »

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.

By way of example: when I worked on payment code in Java, we accepted numeric JSON values in request payloads but they were deserialized into "BigDecimal" fields in our payload classes, not "float" or "double".

Re: No Abstractions: our API design principle

#54

Post by krainboltgreene »

crabmusket wrote: post #50
benhoyt wrote: post #22

Earlier quoted context omitted.

From their docs [1] it looks like they do everything using integers: the amounts are integers in the "minor unit" of currency, for example cents if the currency is dollars. So 1000 means $10.00. In languages like JavaScript where everything is a float64, you can still accurately represent integers up to 2^53, which would be $90 trillion. [1] https://increase.com/documentation/api#transactions

This isn't sufficient to represent prices which often include fractional amounts of cents in non-retail scenarios. Think of AWS server prices per hour.

Funny, because that's exactly what Stripe does (https://docs.stripe.com/billing/subscriptions/usage-based/pr...)

Re: No Abstractions: our API design principle

#55

Post by koreth1 »

Jtsummers wrote: post #44
andrewstuart wrote: post #33

I hate abstractions. Program the thing as it is intended. Why do programmers always need a library between them and the API?

> 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 even though, as this thread demonstrates, the original meaning is still as relevant as ever.

Re: No Abstractions: our API design principle

#56

Post by travisjungroth »

cratermoon wrote: post #49
advisedwang wrote: post #37

Earlier quoted context omitted.

> No Abstractions here really means "just use terms from the underlying system" The article clearly says it also means "no unifying similar objects", which enables the naming decision.

How does that work if, for example, the example given of "Visa and Mastercard have subtly different reason codes for why a chargeback can be initiated, but Stripe combines those codes into a single enum so that their users don’t need to consider the two networks separately.". Unfortunately, the article doesn't explain how Increase handles that overlap. Presumably, as the article states, their customers are the sort t…

I’m just reasoning from my limited experience and the article. Stripe unifies those reasons codes. Increase doesn’t. It might be that the Chargeback has the processor and chargeback code as attributes.

So rather than have a universal “goods and services not received”, it’s a 13.1 for Visa, a 4855 for MasterCard and a F30 for Amex. This matters when the boundaries are different. For example, they all split up the categories of fraud differently.

Re: No Abstractions: our API design principle

#57

Post by yen223 »

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…

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.

Re: No Abstractions: our API design principle

#58

Post by cateye »

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.

Some currencies use more than 2 decimal places. For instance, the currencies of Algeria, Bahrain, Iraq, Jordan, Kuwait, Libya, and Tunisia are subdivided into 3 decimals.

Re: No Abstractions: our API design principle

#59

Post by Pxtl »

yen223 wrote: post #57
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…

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.

Re: No Abstractions: our API design principle

#60

Post by campbel »

yen223 wrote: post #57
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…

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.
Post reply on HN