An API style guide provides guidelines for secure, consistent API design through a clear set of standards and practices. While we have covered the essential elements of an API style guide in a previous article, we haven’t discussed how to automate your API style guide to speed up the API design process.
This article will briefly review the purpose of an API style guide, discuss how you can turn your API style guide into code by using an API linter tool, and address some of the challenges you may encounter along the way.
Why an API style guide?
API design consistency helps developers to pick up any API and start using it quickly. The consistent design also helps to reduce your support costs by reducing the time required to support your API consumers.
An API style guide helps to define the standards and practices that result in well-designed, secure APIs. It usually consists of naming conventions, guidelines for resource collections, patterns for paginating through large result sets, and authorisation techniques.
Great style guides go beyond the common standards and practices, however. They provide guide rails for teams embarking on a new API-driven initiative. They help teams avoid the “analysis paralysis” common when starting a new API due to the many stylistic decisions every team must face.
However, if you wish to evaluate an API against your style guide, you must read each guideline and compare it to the API design to see if any areas of the API are out of compliance. This is where automation helps speed up the process. We need to use an API linter to automate our API style guide.
What is an API linter?
As you may recall, linting evaluates rules against an artefact, such as code or a configuration file. Linters have been used for decades and are a standard tool for development teams.
API linters are tools that execute specific rules to determine if your API complies with your API style guide standards and practices. They are generally run from the command line on a developer’s machine or as part of a deployment pipeline. Once executed against an API description, such as an OpenAPI specification document, it will report the results to help inform the team of any design changes that may be needed.
Using the spectral API linter
This is one of the most popular API linting tools, which allows developers to write rules as code to enforce your API style guide. A rule might look like the following:
```
rules:
paths-kebab-case:
description: Paths should be kebab-case.
message: "{{property}} should be kebab-case (lower-case and separated with hyphens)"
severity: warn
given: $.paths[*]~
then:
function: pattern
functionOptions:
match: "^(\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"
```
Once all of the rules have been defined based on your style guide, a single command can check an OpenAPI Specification document for compliance:
`spectral lint my-openapi-spec.yaml`
If there are errors in the document, the output will look like the following example:
```
28:23 error invalid-ref '#/components/schemas/Account' does not exist paths./api/v1/account.get.responses[200].content.application/json.schema.$ref
✖ 1 problem (1 error, 0 warnings, 0 infos, 0 hints)
The design team must address any errors and review warnings that should be corrected as well. Once all issues are corrected, the linter will output a success message:
```
OpenAPI 3.x detected
No results with a severity of 'error' or higher found!
```
Spectral has built-in rules supporting API description formats such as OpenAPI v2 (formerly known as Swagger) and OpenAPI v3. You can also develop your own custom rules as needed. The fastest path to writing custom rules is to find an existing built-in rule that is as close as possible to your custom rule as a starting point.
Common challenges with API linting
There are a few challenges you may encounter as you start to incorporate API linting into your API lifecycle:
- Your organisation may have a long list of linter rules that must be created to meet your specific needs. While Spectral offers some common functions for composing rules, organisations are often required to stand up a dedicated team to write the code necessary to implement their API style guide using Spectral fully.
- Most linters require that it run via a command-line tool or as a plug-in in your favourite editor. You should provide a short HOW-TO post or video to help developers use the linter locally. The benefit is that they can address errors immediately rather than waiting until the CI/CD pipeline alerts them to the issue much later in the SDLC.
- Every developer must ensure they have the latest set of rules installed locally on their machine to be confident that their API design meets the API style guide requirements. Therefore, it is essential to communicate linter rule updates to your developers or encourage them to check for updates daily to be sure they have the latest rule set.
- If your teams are forced to deviate from your organisation’s linting rules, you will need to support overriding the linter rules on a case-by-case basis.
Wrap-up
As stated in this article, API design guidance and consistency are essential for decreasing the time it takes for your API consumers to use your API. An API style guide guides through clear standards and practices for designing APIs.
Using an API linter helps to automate the API style guide. It will report on any rules that are not in compliance, ensuring that the team can address the problem early in the API lifecycle. As a result, organisations can be confident that their APIs are meeting their preferred standards and practices.
