Leading a world-class API experience
As a leader, looking to build a best-in-class API experience for the developers? It is more business-driven than engineering.
Hey! 👋🏽 This is Tanzim. My mission is to make uncommon knowledge for engineering leaders common. The knowledge I wish I had before is available to you now.
Subscribe to get this newsletter.👇🏼
Teams building world-class APIs might feel the temptation to design them solely from an engineering angle. More often than not, a successful API offering a world-class experience to the developers is designed business-first.
If you are leading such teams, your job is to give your developers the right business context and help them explore the right avenues of thought for a world-class API experience.
Business motivation is the context
Every business shipping an API has different goals in mind. Here is a super generic view of the different motivations for different industries.
Enterprises: Large corporations, for example, Air Canada, could be more interested in integrating with external parties with their API.
Fintechs: Neobanks, wallets, payment rails, etc., are often those who aspire to do everything.
Social media: LinkedIn, Facebook, Twitter, etc., build their APIs as products and aspire to be omnipresent across the globe.
E-commerce: Shopify, Amazon, etc., platforms could be more interested in integrating with partners and offering a rich mobile experience.
Marketing services: MailChimp, Google Ads, etc. APIs are products themselves, and they optimize for increased consumption through their API.
Where your business case falls in context is really up to the specific case.
Get the basics right
With the right business context in mind, answers to the following are a bare minimum for a successful API:
Is there a specific purpose for your service to exist? If you cannot write what this service does in one sentence, you probably do not need it.
Do you have a list of specific business cases/flows that this service should serve? If you do not, you have not done the homework detail enough. Do not jump into design and coding right now.
Are you designing the API around the business domain, or based on your convenience? Just because you could join the user and transaction tables easily if you keep them together does not ensure a good domain separation.
Is your API a delight or burden to use?
Is your API saving time for its consumers’?
Are you offering a self-documented API (e.g., OpenAPI), well-written tutorials, code samples and SDK?
Does the API documentation answer the right questions? Examples:
“What can I do using this API?”
“How do I do something with this API?”
Is this API going to (de)increase the API consumers’ cognitive load?
To SDK or not SDK: A tricky question
Should you build an SDK? When there are subsequent calls involved, such as transactions, authentication, etc. building an SDK seems a very lucrative option, because it may bundle several calls into a single call abstracting away many avoidable details improving the developer experience by a lot. However:
Is it not introducing opaqueness in front of a transparent (API) layer?
Will it not be expensive to maintain an SDK every time the API is changed?
Will it not increase the cost of fault investigation for not knowing whether it is in the API or SDK?
In most cases, you can avoid building an SDK. Perhaps your API design needs more work, instead.
Trust: the hardest question
Does your API promote trust?
Here is a limited list of qualities that the API must demonstrate to inspire trust. The API must:
Be available and accurate for the majority of its lifetime
Be a result of deliberate and thoughtful design vs. letting it organically grow as the business grows
Use industry standards and nomenclature
Have fine-grained control over (e.g., role-based) security to inspire confidence
Have defensive coding, e.g., validates data, gracefully handles faults vs. crashing
Have versioning, backward compatibility and support
Be supported with proactive communications
Be covered with adequate automated tests to catch the bugs before its consumers
APIs are consumed by humans and machines alike.
We often exclude both humans and the business from our thoughts when we design for machines alone.
An API designed around business and for the humans makes a profit and is loved.
Subscribe to get this newsletter.👇🏼