An API definition may be thought of as an electronic equivalent of a receptionist for an organisation. A receptionist is normally the first person they see when visiting an organisation and their duties may include answering enquires about products and services.
This is similar to an API definition, when someone wants to do business electronically, they would use the API definition to obtain information about the available services and operations.
My thoughts are, API’s should be built customer first and developer second. Meaning an API needs to be treated as a product and to make it appealing to a consumer, it needs to be designed as intuitive and usable with very little effort.
Having standardised API definition documents across all your API’s, allows a consumer to easily navigate around your API’s as they will all have a consistent look and feel about them. This specially holds true when there are multiple teams developing Microservices for your organisation. You don’t want your consumers think they are dealing with several different organisations because they all look and behave differently. Also, when generating the client object models from several different API definitions from the same organisation, you want the property names to all follow the same naming conventions.
To ensure uniformity across all API schema definitions, a linter tool should be implemented. One such open-source tool is Spectral https://github.com/stoplightio/spectral from Stoplight, however there are many other similar products available.
Ideally the validation should be added as a task to your CI/CD pipelines when committing the changes to your API definition repository.
Using Spectral in MS DevOps API Projects
Spectral provides the capability to develop custom rules as a yaml or json file. I typically create a separate DevOps project to store these rules inside a repository which may be shared across other API projects.
Below is how I have setup the repositories section in the pipeline to include the linter rules and the API definition.
After downloading the Spectral npm package in the pipeline, I then run the CLI command to start the linter on the schema specification document which is normally stored in a folder called ‘specification’ in the corresponding API repository.
An example of the pipeline job can be seen below. Here the job failed due to some rule violations.
The build pipeline and sample rules can be found here https://github.com/connectedcircuits/devops-api-linter
Hope this article now persuades you to start using Linter across all your API definitions.
Enjoy…