Updated on by Daniel Twigg
Our interviews are with conversations with our Connector Developers about API development. We spoke with Daniel Ridgway about his experiences with the vast variations of API documentation.
How important is documentation to API development?
Documentation for API development is crucial, there is nothing more pleasing than seeing well-constructed and detailed documentation when taking on a new connector. If you can import Postman, even better, as you can jump right in and start moving data around easily.
What is a sign of a good API documentation format?
The hallmark of good API documentation is that it is maintained regularly and kept up-to-date with any changes. As well as if the documentation format is well laid out, easy to navigate, and with all required parameters for a request to be successful, including examples of the expected responses is helpful too.
Other aspects that make for a good documentation format are walkthroughs and tutorials. I’ve always found that making documentation easily accessible, and having well-maintained support sections, for anyone with additional questions and queries to aid with development is the most useful. Seeing how quickly they’re responded to is a great indicator of how much attention is paid to their documentation.
It is important that authentication sections are concise, and 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 it’s important to think about your potential users.
Can you give an example of working with a poorly documented API? What challenges did you face during the API development process?
Not a specific example but poor API documentation has usually been hurried together and often dumped into a Word Doc. They tend to be littered with spelling mistakes and copy-pasted request and response bodies, which means they end up being incorrect. It doesn’t help if the documentation also includes deprecated features that are no longer available.
Using poorly documented API during the development process demonstrates not only technical challenges but also the challenge of trying to decipher someone else’s mistakes and correcting documentation as you go along. The additional time this adds to the job can often be frustrating, as the only way to progress is through trial and error. It comes close to having no API documentation at all. Correctly guessing endpoints and request parameters the first time is quite satisfying though.
What development resources do you find the most useful when working with an API?
Definitely, Google, which inevitably leads to StackOverflow. There aren’t any documentation tools or resources in particular that I use on a consistent basis. I find using specific search terms, for example, 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, and there’ll always be more than one solution.
Do you have any specific APIs you’ve worked with that have outstanding documentation?
I find that most Swagger API documentation available is the most useful. I’ve already mentioned Postman, but 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.
Looking for an embedded iPaaS? Get in touch or check out our documentation.
