API Interviews – API documentation: the do’s and don’ts

Updated on by Daniel Twigg

Our API 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 good API documentation format?

The hallmark of good API documentation is that it is maintained regularly and kept up-to-date with any changes. 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 are helpful too.

Other aspects that make for good API documentation format are walkthroughs and tutorials. I’ve always found that making documentation easily accessible, and well maintained support sections, for anyone with additional questions and 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.

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 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 API 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 to be 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.


If you are using our Cyclr platform or just interested in how it works feel free to check out our documentation

Looking for more about working with APIs, read our two other interviews with members of Cyclr’s connector development team where we talk about the challenges of working with APIs, and working with different API authentication types.

Avatar for Daniel Twigg

Daniel Twigg

With over 10 years experience in the Digital Marketing arena, covering industries including IoT, SaaS, fitness, computer gaming and music, Daniel has been Cyclr's marketing manager from the early days of the platform.