🧠 Knowledge Series #16: How to read API documentation confidently

API docs can be confusing. Here’s what you need to know.

🔒The Knowledge Series helps you plug the gaps in your tech knowledge so that you feel more confident when chatting to technical colleagues. Clearly explained in plain English. One topic at a time.

 If you’re a free subscriber and you’d like to upgrade to receive them you can do so below. Or you can find out more about paid access here.

---

Hi product people 👋,

If you’re ever able to work on API product development with confidence you’ll need a solid understanding of how the API works. API documentation is normally the starting point for this - and if you’re not an engineer, trying to navigate your way around a company’s API docs can be confusing. 

In this Knowledge Series, we’ll cover all of the essential bits that are important to know about API documentation so that the next time you’re tasked with finding out more about the capabilities of a third party API, or you’re thinking about productizing your own APIs, you’ll have a better understanding of how API docs work.

Coming up:

• Why it’s useful to learn how to read API documentation

• The most important bits of API docs to know about

• A closer look at some examples together

• Differences between API docs and SDKs

---

The Knowledge Series

Why bother learning how to read API documentation?

I once learned the hard way when I forgot to ask fundamental questions about an API partnership and didn’t fully read the API docs ahead of time. 

I was working at a large commercial bank which had strict rules about which third party providers we were able to work with. We were on the lookout for a new email provider for sending transactional and marketing emails and in an ideal world we would have been able to choose a market leader but thanks to the strict procurement processes, our vendor choices were limited.

After a lengthy series of presentations, myself and a colleague decided to pick a vendor which seemed to offer the best API functionality for the use cases we needed. It was only when I got back to the office and ran everything past our engineering teams did we realise that the API docs were all in a clunky old SOAP / XML format, rather than REST, which would render the partnership impossible. That was not a pleasant experience 🙂.

Learning how to read API docs confidently will give you the opportunity to spot any red flags. In this case, the fact the APIs were using SOAP was a red flag, but other things like outdated APIs that haven’t been updated in 5 years would also be considered a red flag.

API docs are your single source of truth for API integration testing and when you’re managing API integrations, you’ll need to use the docs to check the API is behaving as it should.

Being able to read API docs confidently can also help you to explore new opportunities for your product. After deep diving into some API docs, for example, you might discover new bits of functionality or features that you previously had no idea about. This could spur new feature ideas and help you build out your product strategy in ways you hadn’t previously considered.

The important parts of API documentation to know about