|Learn To Document Your API Correctly|
|Written by Nikos Vaggalis|
|Tuesday, 05 September 2023|
"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:
What is API Documentation
The Business Impact of API Documentation
How to Write Good Documentation
Documentation Techniques & Tools
Documentation Best Practices
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.
or email your comment to: firstname.lastname@example.org
|Last Updated ( Wednesday, 06 September 2023 )|