No Abstractions: our API design principle

&gt; 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.<p>You could always do both.<p>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 fewer simple operations for the most common use cases - which some of your clients might be implementing their own half-baked versions of anyway.<p>If you maintain a clean separation between the two, having both in place might mean there is less pressure to add abstractions to the low-level API, or to add warts and special-cases to the high-level API. If a client wants one of those things, it already exists - in the other API.<p>Bonus points for providing materials to help your clients learn how to move from one to the other. You can attract clients who do not yet have deep knowledge of payment network internals, but are looking to improve in that direction.

I like the part that explains why Increase choose a different approach. Contexts matter a lot when you design something fundamental, but people usually don&#x27;t appreciate this enough.

No Abstractions here really means &quot;just use terms from the underlying system&quot;, which is a good naming principle in general.<p>Problems inevitably arise over time when there&#x27;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 Federal Reserve, deprecates Input Message Accountability Data and switches to a new thing?<p>Maybe things are a lot simpler in the payment industry than they are in transportation or networking protocol. If I built a packet-switching product based on X.25 and later wanted to also support tcp&#x2F;ip, what&#x27;s the right abstraction?

Love the article.<p>If you love Stripe (and as a designer and tech entrepreneur I do – Stripe&#x27;s simplicity and front-end skill is incredible) you might look at them and copy their ability to simplify and deliver polished experiences.<p>But the real mastery of Stripe is that they know their customers — and the simplicity they crave.<p>By this article is sounds like Increase does as well and has forged a similar laser-focus on what their customers need to build terrific design guidelines for making products. Inspiring to see.

This is similar to Domain-Driven Domain&#x27;s &quot;Ubiquitous Language&quot; design pattern, making your implementation use the same real-world terminology used domain experts.<p><a href="https:&#x2F;&#x2F;thedomaindrivendesign.io&#x2F;developing-the-ubiquitous-language&#x2F;" rel="nofollow">https:&#x2F;&#x2F;thedomaindrivendesign.io&#x2F;developing-the-ubiquitous-l...</a>

This is a great example of the concept “ubiquitous language” from Domain Driven Design.<p>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.<p>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.

Author here - this has been a useful mindset for us internally but I&#x27;m curious if it resonates externally. I&#x27;d love your feedback!

If we didn&#x27;t have abstractions like POSIX, applications would need to write an adaptor for every supported file system.

Interesting.<p>The title of the concept is misleading, &quot;No Abstractions&quot; here doesn&#x27;t literally mean &quot;no abstractions&quot; but instead &quot;we use this specific set of abstractions, and not others&quot;. And the specific subset they describe is worth discussing! But it&#x27;s of course a set of abstractions.<p>E.g.<p>&gt; <i>For example, the parameters we expose when making an ACH transfer via our API are named after fields in the Nacha specification</i><p>A specification is an abstraction.<p>&gt; <i>Similar to how we use network nomenclature, we try to model our resources after real-world events like an action taken or a message sent. This results in more of our API resources being immutable [...] and group them together under a state machine “lifecycle object”.</i><p>Immutability (in this sense) and &quot;lifecycle objects&quot; are abstractions.<p>&gt; <i>If, for a given API resource, the set of actions a user can take on different instances of the resource varies a lot, we tend to split it into multiple resources.</i><p>Another abstraction, just splitting at a different level than the Stripe API.<p>This is a set of design decisions and abstractions. Definitely not a &quot;no abstractions&quot; principle. I would say the most important decision they seem to have made is to generalize as little as possible -- and generalization is indeed a kind of abstraction. Maybe &quot;Fewer Generalizations&quot; would have been a more accurate title?

&gt; Monthly fees for users building on Increase vary by use case.<p>I am currently adding public API access to AI-powered text-to-SQL endpoint with RAG support and the my biggest issue is the pricing. Anybody have a ballpark figure what we could be talking about here? Pricing must account for OpenAI tokens (or perhaps letting them add their own OpenAI token), database usage and likely caching&#x2F;rate limiting setup down the line.

But the entire API is an abstraction...<p>So the benefits are:<p>Audits<p>Network&#x2F;infra<p>Time to market<p>Single API<p>Less code<p>Risk (sometimes)<p>The downside:<p>1. Slow or missing propagation of underlying features.<p>2. Hidden business logic.<p>3. Risk of changes in pricing models and so on.<p>4. Single point of failure.<p>By method, let&#x27;s talk about the downsides:<p>1. Not the biggest risk here. But for some reason features that are new or will save you a lot of money does not propagate as fast other things.<p>2. Many services like payment gateways are expected to hide some aspects of the underlying services. What does this hide?<p>3. The big risk with something like this used to be vendor lock-in. Today it is almost always acquisitions. Is this really a product? Will it be merged and sold together with something that I don&#x27;t want?<p>4. Obvious<p>Overall I think these types of services are the most useless. Abstractions that are not simplifications should mostly be avoided. I also think one needs to be extra careful if this only sits between you and other services. That is not a product in general.

&gt; 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.<p>This is indirection, not abstraction. Abstraction raises the semantic level.

So they say parts of the API structure are based 1-1 on externally controlled specifications.<p>What happens if those specifications evolve or change?<p>New API?

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&#x27;d be curious to see how they are handling this case as it can be a real head-scratcher.

I think the point the author is trying to express here, is that it can be a useful in API representation, to couple the design with other representations designed by other parties.<p>I don&#x27;t think &quot;No Abstractions&quot; is a good framing for this, although I would have to admit I dislike use of the term abstraction, as it implies there is a hierarchy of representations.

If there&#x27;s no abstraction, what&#x27;s your value-add? I don&#x27;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&#x27;re just a middleman extracting rents.<p>You might find it more valuable to state your position as &quot;carefully scoped abstractions&quot; to make it clear what value you add.

Java engineers need to see this. Goddamn Proxies, Factories, and Beans. Fragments, Surfaces, Runnables.

No abstractions? So their API lets me control the individual registers on their CPU then?

Also it greatly helps to not overuse nouns and try to forcefully model verbs with resource entities.

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 think this is better than Stripe’s abstract everything approach even for people who are not into payments. Stripe has built a very leaky abstraction.

Strong work Jack!

TLDR: we are special and created our own standard.

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