API Interviews – API documentation: the do’s and don’ts
10th January 2019
This month we talk to our very own Daniel Ridgway about his experiences with the vast variations of API documentation.
How important is documentation to API development?
Crucial – as much as I like to pretend I’m Lovejoy/Columbo/Poirot, there’s nothing more pleasing than seeing well constructed and detailed documentation when taking on a new connector. If you can import into Postman, even better, as you can jump right in and start moving data around easily.
What is the hallmark of a good set of API documentation?
Maintained regularly and kept up-to-date with any changes – always a sign of good documentation. Detailed, well laid out, easy to navigate, with all required parameters for a request to be successful – including examples of the expected responses are helpful too.
Walkthroughs and tutorials are useful, but I’ve always found easily accessible (searchable!) and well maintained support sections for anyone with additional questions or queries to aid with development to be the most useful – seeing how quickly they’re responded to is a great indicator of how much attention is paid to their documentation.
Maybe more importantly, authentication sections that are concise – but guide you through each step smoothly, as this is often your first step in development. I think it’s vital to remember that not all your API users are jargon-busters, so think about your potential audience.
Can you give an example of working with a poorly documented API? What challenges did you face?
Docs that have been hurried together – often dumped into a Word doc, littered with spelling mistakes and copy pasted request and response bodies (which means they end up being incorrect).
The challenges here are not only technical, but trying to decipher the mistakes and correcting someone else’s documentation as you go along – no need for everyone to experience the same pain, hey! However, the additional time this adds to a job can often be frustrating, as the only way to progress is through trial and error. It’s pretty close to having no docs at all. But correctly guessing endpoints and request parameters first time is quite satisfying.
Deprecated features that are no longer available should be removed.
What development resources do you find most useful when working with an API?
Google! Which inevitably leads to StackOverflow – there aren’t any resources in particular that I use on a consistent basis. I find using specific search terms (e.g. the API you’re working with and a couple of keywords to indicate the problem) to locate others who have had similar issues.
More often than not, you’ll find that it’s a common thing that most people struggle with, so you don’t feel like such a dumb-dumb – and there’ll always be more than one solution.
Do you have any specific APIs you’ve worked with that have outstanding documentation?
Outstanding? Nope. I do find that most docs that are available on Swagger to be the most useful, though. As I’ve already mentioned, with Postman, you can usually make real-time calls directly from the documentation. This is a huge bonus, as you can see straight away what you’ve got to work with.