Announcing Apiary Constitutions
By Corvax (@jedenbod, corvax@apiary.io) on 25 Apr 2018
We’ve been a long time proponents of practices like design-first and contract-driven development. For a while, part of our Apiary Pro offerings are also Style Guides. It’s a way to programatically define and check your company API Style Guides. For most of the world, API Style Guides are these long, static PDFs written by architects, without any tools to apply them to the API design phase or check how well implemented they are.
Apiary Style Guides are a tool for checking consistency of your API Designs. They are integrated into the Apiary Editor, but writing your own rules used to be a laborious task. We wanted to simplify the experience.
Meet Constitutions
Apiary Constitutions is a tool for writing, testing and managing Style Guide rules. Rules are written in JavaScript and works for both API Blueprint and OpenAPI Specification definitions, thanks to our API Elements tooling.
It’s a repository prepared for the rules development. Comes with a default set of rules you have enabled when you start using Style Guide in Apiary. You can easily reuse them or make them your starting point for custom rules. Our goal was to supply you with a way to have a simple build and test commands.
How does it work?
To stay true to the example driven development, Constitutions will require of you to supply both passing and failing example documents for your Style Guide rule. So you can see how a correct usage looks like. This also helps you test the rules as you develop them. These examples are then reused for generating a readme, which should serve as a readable API Style Guide reference.
We then use Webpack to build a single file with all your rules, which is then run through our rules engine. We recommend to fork the Constitutions repo if you wish to have your own API Style Guides in git.
Updates to the Apiary CLI
Constitutions will simplify writing the rules. To allow you better integration of these rules into your API Design flow, we also added the styleguide option to the Apiary CLI. With it, you can fetch and test your Apiary Style Guides against a local document.
Next we added --push option to the CLI, so you could build rules locally or in your CI and synchronise them with the rules you enabled in Apiary Editor.
We hope this will make live easier for both Style Guide creators and consumers! For any questions, let us know either on support@apiary.io or in GitHub issues.