Manually writing and enforcing API style guides is a painfully tedious and slow process. By automating your API style guides as much as possible, you can provide a great developer experience for both your internal developers and your API users.
Software organizations use automation to handle repetitive and time-intensive tasks. Building your API style guide should not be an exception; automation is a powerful and important tool to leverage when developing your API style guide. With an automatic style guide, you can ensure rapid API development and a consistent developer experience across your organization. However, some aspects of your API development still need human input.
In this article, we’ll discuss what you can automate and what you should handle manually to get the best results for your organization. This will help you get the full benefits of automation while incorporating human input where it matters most.
What to automate?
When deciding what to automate in your API style guide, you should look for certain characteristics. Anything that a script can do faster and/or more accurately than a human should be automated. Linting, version control, and publishing are some of the important aspects of your API style guide development pipeline that should be handled by scripts.
While humans can do these things, automated scripts work faster and more accurately. Let’s discuss each type of task and why you should automate them. We also covered this topic in a recent podcast episode of API Intersection with API Handyman, Arnaud Lauret.
Linting
Linting is when you use a set of rules to check your API design complies with your style guide. While you could have a human editor that reviews every line that gets added to your API Design, automating these reviews speeds up the design review process by giving feedback as you write it. Your linter will give helpful errors to enforce the rules in your API style guide when your team is writing documentation. This minimizes human error by ensuring that your style guide remains consistent and detailed. Your organization can choose your linting rules and update them to further improve your developer experience.
Version Control
As your API design changes over time, your organization will need to change your API style guide if you’re following API versioning best practices. Version control is when you track the changes you’ve made so that you understand when you changed them, what you’ve changed, and who changed them. Version control is important to both the documentation team at your organization and your API’s users. Your users will know if your documentation has changed recently, so they can update their software accordingly. For your internal teams, version control makes it easy to troubleshoot your style guide, revert changes when necessary, and understand why a change was made.
Publishing
You’re going to need to publish your style guide for the developers working on your API. While you could re-upload all your documentation after every change, this adds unnecessary human input to your style guide process. You can use software to automate this part of your build process so that only updated content is uploaded, and you don’t have to use computer resources to rebuild your entire style guide after every update you can make it part of your Continuous Integration.
The instant feedback from automated features significantly improves your developer experience. However, it isn’t always the best tool for the job, and there are aspects of your style guide that cannot be automated. In the next section, we’ll discuss when human input is a better choice than automation and why automation isn’t suited for these situations.
The Role of Human Input
While it’s important to use automation when you can, human input is still a necessary part of creating and maintaining your style guide. Human input is important for the decisions that lay the foundation for your API style guide. There are a lot of choices when it comes to linting rules, naming conventions, and architectural style. There isn’t a single “correct” choice for any of these, and you can’t automate these decisions because they are informed by your API’s context and your organization’s needs.
Architectural Style
The architectural style of your API is a crucial part of your API style guide. You can’t build your endpoints before choosing between REST, RPC, Hypermedia, or an alternative architectural style. The architectural style is the first decision you’ll have to make, you can’t start building your API style guide before you’ve chosen an architectural style. This defines what your endpoints will look like and how developers will access them. This decision can’t be automated away, since each style has different constraints and you’ll have to choose what works best for your organization.
Linting Rules
Next up are your linting rules. We’ve already discussed why your linting should be automated, but the rules that govern your linter need to be set by a human. You’re in the best position to understand what the developers writing your API should include, and change the linting rules as your needs change. Your linting rules can look for typos, missing types, bugs, and naming standards. You should choose a set of linting rules that leads to the best developer experience.
Naming Conventions
Your organization also needs to choose naming conventions for your API style guide. Naming conventions ensure that your endpoints are named consistently, and make it easy for the developers at your organization to choose names that will make sense to external users as they develop your API. There’s no way to choose naming conventions with a script, so your developers should ultimately choose a naming convention and stick with it to maintain consistency.
Human input is best suited for subjective decisions because your organization’s context determines what choice will work best for you. Now that we’ve discussed when human input is a better choice than automation and the situations that favor each approach, you should be able to choose the right tool for each job when building your API style guide.
How Much Automation?
Now that you know which situations automation is best for, and when human input may be the better option, you need to decide how automated your style guide will be. Each additional task that becomes automated will save time spent writing and enforcing your style guide. Ideally, you should try to get as many tasks as possible automated. This frees up team members to handle other tasks, especially tasks that can’t be automated. Let’s talk about how automation and human input complement each other to get the best results for your API style guide.
Some processes, like linting, need a combination of both human input and automation. Your linting rules should be defined and reviewed by members of your team because they understand the needs of your developers. Once you’re satisfied with your linting rules, you can hand off the rest of the work to your linting tool. Automated linting is instant, accurate, and improves your developer experience. This combination of human input and automation will be great for your API style guide.
Additionally, while it is important to automate your publishing process, you need to first determine that publishing process. If you’d like to publish updated information as fast as possible, you can skip the human review and publish new content immediately. If your organization has great linting rules, publishing immediately may be the better option for you.
You won’t be able to automate every aspect of your style guide; some tasks will always need human input. But, automating tasks in your style guide development process will free up team members to handle other tasks, like developing your API and writing documentation. Focus on automating what you can so that your organization can maximize the benefits of an automated API style guide.
If you need a hand automating your API style guide for the first time, try Spectral, a JSON/YAML linter that is preloaded with a default linting ruleset. The default linter rules are a great foundation if your organization doesn’t yet have custom rules, and you can write a ruleset that fits your organization’s needs. For a deep guide on Spectral, check out our recent blog.
