Stop the manual API plumbing

APIs rely upon bespoke, manual, and tedious work. Typical time sinks are poor documentation, undocumented behavior, non-standard API design, custom authentication schemes, unclear limits, and terms of service. Yet, the real pain comes later when APIs change. Once you lay down the wires, you are in the business of perpetual maintenance. Sure, you can close your eyes and pray, but APIs are a dependency and, potentially, a liability. But it doesn't have to be.

Most of us want to get to the value delivered over APIs quickly. Chances are you don't care whatever was the fancy API style in 1998. Besides, it will be different with the very next API you need to connect. So why bother?

Use-case abstraction

The solution lies in the use-case level abstraction on top of APIs. The concept is simple. If you are an API consumer, integrate with the use-case, not with a provider: “Send text message” vs. POST https://api.twilio.com/:version/messages.json. If you are a provider, publish your business capabilities: “Make a payment with PayPal” vs. customerPaymentMethodPaypalBillingAgreementCreate(billingAgreementId: $billingAgreementId, customerId: $customerId) (source). The technicalities of the connection can be dealt with autonomously with the right metadata.

Hexagonal architecture

The implications of use-case abstraction are profound. The clean, hexagonal architecture results in decoupling client and server and enables independent evolution, breaks technical vendor locks, speeds up the development, and radically reduces maintenance.

To learn about the use-case abstraction for APIs, check out Superface GitHub profile.