Leading a world-class API experience

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.

(I write for senior engineering leaders. 750 people have received this post in their inbox today. If you haven't already, consider subscribing to my newsletter.)

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 (refer to the chart below).

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.

(I write for senior engineering leaders. 750 people have received this post in their inbox today. If you haven't already, consider subscribing to my newsletter.)