Improving API Documentation and Automation
In any startup, managing APIs across multiple services is a common challenge. We faced three main issues:
- Documenting APIs
- Publishing the documentation
- Updating it whenever APIs change
Each of these had its own set of questions: how to do it, where to do it, what tools to use, and who would take ownership.
To tackle this, our team decided to consolidate all APIs into a single repository called APIHub. Each service’s APIs were stored in a simple and consistent format:
GET | POST | PUT | DELETE | PATCH
${baseurl}/endpoint
{
"body": "if present"
}We named the files according to their function. Below is an example of a .l2 file for a "Leave Apply" API, along with a sidebar showing other APIs in the repository:
[Image: VSCode APIHub Leave API]
Improving Documentation Practices
We made it mandatory to include the corresponding .l2 file in every pull/merge request. If it wasn’t there, the request wouldn’t be approved. This simple rule increased API documentation consistency across the team.
[Image: Merge requests]
From Documentation to Execution
We soon realized that manually testing APIs by copying URLs and payloads to tools like Postman was time-consuming. So, we built a CLI tool called Lama2.
Lama2 is a plain-text API manager optimized for Git-based collaboration. With Lama2, you could pass a .l2 file as input, and the CLI would execute the API and show the response in the terminal:
[Image: Lama2 cli]
Taking it to VSCode
To streamline things further, we developed a VSCode extension. It came with features that made our workflow even smoother:
- Execute .l2 files directly in the editor
- Copy the file’s Git URL for easy sharing
- Prettify JSON payloads
- Generate code snippets for any language from .l2 syntax
- Create templates for new APIs in seconds
- Auto-completion of variables using LSP
[Image: Options]
The Next Problem: Scaling Documentation
As our APIs grew, we asked ourselves:
- Why manually document APIs for each service?
- Isn’t it time-consuming to update documentation for every change?
And that’s where the next chapter of our journey begins…
Conclusion
In this article, we discussed how we improved API documentation and automation in our startup. We consolidated all APIs into a single repository, created a simple and consistent format, and built a CLI tool called Lama2. We also developed a VSCode extension to streamline our workflow.
FAQs
Q: What is APIHub?
A: APIHub is a single repository for all APIs in a startup.
Q: What is Lama2?
A: Lama2 is a CLI tool for managing APIs, optimized for Git-based collaboration.
Q: What is the VSCode extension?
A: The VSCode extension is a tool that streamlines API development and testing in the editor.
Q: How does the VSCode extension work?
A: The extension allows users to execute .l2 files directly in the editor, copy the file’s Git URL, prettify JSON payloads, generate code snippets, create templates, and auto-complete variables using LSP.
