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.
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
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.
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.