"API Documentation Best Practices" is a brand new short and free course by APISEC University which looks into why documenting your APIs should be an essential part of your software development cycle and not an afterthought.

APIsec University is hosted by Corey Ball, a true cybersec expert and author of the book Hacking APIs - Breaking Web Application Programming Interfaces, published by No Starch Press. We've already reported on APISEC University in Learn To Protect Your APIs By Hacking Them, describing the security-oriented API Security Certified Expert course.

This one again is great being taught by Jason Harmon, chief technology officer at Spotlight who has over 20 years of experience in the technology and API world. Jason manages to provide insight and the best practices while being quick and easy to follow in tackling the important aspect of documenting your APIs, while offering plenty of reasons to do so.

The syllabus comprises of the following modules, each one split into further chapters:

Introduction
Introduction to API documentation and the agenda for this course.

What is API Documentation
Understand the value of documentation, types of documentation, and who creates documentation.

The Business Impact of API Documentation
Understand why good API documentation matters for security, governance, and partnerships.

How to Write Good Documentation
In this module we’re learn how to write good documentation and walk through a live examples.

Documentation Techniques & Tools
Discover tools and techniques for creating documentation, and their respective pros and cons.

Documentation Best Practices
Wraps up the course with some tactical best practices to help improve your API documentation.

So let's begin by asking, "what is API documentation?" In Jason's words :

In simple terms, this is a human readable description of how developers will enable machines to communicate with each other. It's a mouthful, but this is my attempt to wrap up a few different things.

One is documentation is for humans. This is for people to read and understand. The developer aspect, that's not the whole story. We're not just talking about documentation for developers, but at the end of the day, the outcome of why people are engaging with these sorts of things is for developers to create connections between machines. That's what APIs are all about.

In other words, an API should be well documented both from a technical perspective in order to address developers and callers of the API, but also from a business perspective in order to address managers and business people since most developers are not the ones making the buying decision.

Then he considers APIs as reference material and looks at examples of how they can be improved by comparing them to Stripe's APIs which he considers as the gold standard.

The next chapter is where he looks at the intersection of api documentation and security as he explains that bad documentation can lead to exploits.

"How to Write Good Documentation" digs into the simple question of who is the targeted audience. Are these internal developer oriented documents? Are they end consumers who might be external to the company? It's always important to start with those relationships to understand who's going to be using it so that you're using the right voice and the right approach in enabling them.

"Let’s document a fake API together" has to be the most valuable module of the course in my opinion as it shows how to actually go about it by employing all the best practices thus far encountered.

The final module "Documentation Techniques and Tools" looks at the advantages of using a Spec-based method to documentation.

This concludes the course. In under 2 hours we learned why documenting your APIs is crucial, how to address different target groups, how to employee best practices as well as went through a practical example doing it. If you are developing APIs then this is a must watch.

More Information

API Documentation Best Practices

Related Articles

Learn To Protect Your APIs By Hacking Them

To be informed about new articles on I Programmer, sign up for our weekly newsletter, subscribe to the RSS feed and follow us on Twitter, Facebook or Linkedin.

Comments

Make a Comment or View Existing Comments Using Disqus

or email your comment to: comments@i-programmer.info