If you are in the business of software integrations, your API is your brand’s digital handshake with the world. How you present your API and documents directly reflects your values as a business. If you keep details clear and familiar, you'll have developers singing your praises. Overcomplicate it, and you’re basically paving the way for your competitors.
I’ve been on both sides of the equation, as a builder and customer. I’ve built and launched APIs for multi-sided marketplaces and designed large-scale operations systems automated entirely by API. I've felt the thrill of a seamless integration and the frustration of a poorly organized one. Trust me when I say this: a little added care in your API design goes a long way. It can be the factor that differentiates you from competition.
Who is this essay for? The PM or Engineering Lead who is managing / launching APIs and dealing with technical constraints, scalability, and user experience.
I get how complicated integrations can be. Your API might need multi-level schemas or intricate procedures. That complexity doesn’t have to bleed into your design and documentation. Remember why you built an API in the first place? To make your app easier to use. So let's keep things simple for your most important customer, the developer.
Stop complexity spillover
Product teams have a tendency to, after solving a hard problem, overcomplicate their products. Integration appears obvious to team members, but too intricate for customers. This is complexity bias playing out: the complicated option for your API seems like the simplest approach. It typically happens when teams have been in the weeds too long. There are a few ways to fight against this tendency:
Abstract. When overly complex details are surfaced or a schema is exposed that customers have little reason to change, abstracting these details to something like a simple label can be helpful.
Get an outsider’s perspective. It helps to have someone, a potential customer or trusted friend, look over your API experience end-to-end. Ask them to highlight anywhere in the documentation that doesn’t make sense or where they get stuck during integration.
Play a proxy customer. If you can’t get someone outside your team involved before going live, have someone play the part. Pretend that for a day, one person on your team is a customer. Set them up with the tech stack and problems your customers do. Pretend they have no insider-knowledge about your company or product and have them walk through the experience. They should take notes on everything that creates friction. Your team can read through notes and address issues during a debrief the following day.
When in doubt, do and say less. "Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away." [1]
Don’t reinvent the wheel
API standards exist! Thanks to the advances in cloud computing, businesses are converging around AWS, Azure, and GCP as their service providers (a combined 65% market share). Multi cloud architecture is also gaining steam.
These factors are pushing Microsoft, Amazon, and Google to have consistent and reproducible elements that fit nicely together. This standard has trickled downstream to their business customers, which makes sense: if customers are integrating with parts of your API and Azure, they ideally have a consistent integration experience. I see this trend more as a bar of quality, rather than a playbook to follow. If you’re looking for a playbook — REST and GraphQL are widely adopted API standards, but neither dominate.
Be careful not to prescribe frameworks unintentionally. If you want a technology-agnostic API, be intentional about what constraints you build into your design. The bigger tech companies tend to make tradeoffs in favor of their tech stacks and that might not be what your customers want.
Follow principles of good API design and documentation
The best APIs look good inside and out. Familiar functions, well designed documents, and logical ways to customize.
It should come as no surprise the golden standards for APIs are set by the most developer-friendly businesses. Stripe, Twilio, Github, and Shopify have built cultures around making software look and feel good. These are the API experts. You can learn a lot from simply walking through their integration experience as a customer: get a feel for just how easy it is to follow, learn, and use. Here are four principles that stand out:
1. Stripe - Simple means fewer lines of code:
Stripe alone has raised state of the art for developer tools more than any business in history, famously launching with a product that only required “7 lines of code” to integrate. You can follow their lead and keep to simple code and onboarding. Then, do everything you can to maintain this simplicity as your business scales.
2. Twilio - Make directions easy for anyone to follow:
Twilio’s docs are super easy to follow, even for non-technical readers. They’re organized by business case and use smart visuals to explain how features integrate with your system. Easy docs should be met with easy to use APIs (which typically have programming language options).
3. Shopify - Provide multiple APIs:
Shopify has been making storefronts online for almost two decades, and with that comes a lot of versions and iteration. One way to keep developers happy no matter when they build, is to offer multiple APIs. This strategy probably requires extra effort to maintain and feature gaps, but if you can handle the changes and it keeps your most loyal customers happy - could be worth it.
4. Github - Meet developers where they are:
Github makes integration easy from just about every interface software developers use. As a developer platform, being integrated with these tools for ease-of-use to their customer base is valuable to them. While you may not have the same product, this tactic could work well for your needs (e.g. importing your API to Visual Studio Code).
Avoid common pitfalls
Your API and documents need to evolve just as rapidly as your product. Your business can fail customers if an integration breaks or information is inconsistent, causing potentially significant losses. Avoid these careless and often unintentional traps:
Lessening your standards because it’s a private API. If your API serves 5 or more customers, don’t lessen your standards regardless where it’s facing.
Keeping your intended reader in the dark. Describe the persona you’re targeting early in your materials to make it overtly clear who your materials are for. Nothing worse than learning about a topic for an hour to find out you can’t finish steps 12-15.
Falling out of date. Set reminders or schedule recurring meetings to revisit documentation and design decisions (e.g. each quarter). Letting your documentation or schema fall out of date creates headache for everyone.
Ignoring customer costs. The size of your API call should be minimal and optimized as you grow - you save customers money for every bit of code you don’t need to send or retrieve.
Why you should care (about overthinking your API)
You should care about simple APIs and scalable practices, because integrations are what connects the modern internet today. APIs are here to stay. We are all accessing applications calling other applications, and doing more of it each year.
Making any number of these improvements will payoff in terms of the money you’ll save on technical operations. But more importantly, keeping your API simple and easy to follow positions your business to take advantage of a not-so-distant-future where integrations are handled automatically. If your API has extra manual effort or undocumented nuance, you’ll be left out of that future market’s upside.
To recap, you can do things big and small to simplify your API and improve your customer’s overall integration experience:
Keep it simple: (i) Abstract, (ii) Get an outsider’s perspective, (iii) Play a proxy customer.
Don’t reinvent the wheel: Start with market makers like AWS, Azure, and GCP.
Raise your standards: Learn from API leaders like Stripe, Twilio, Shopify, and Github.
I look forward to seeing what you build.
-----