Apiary Constitutions

Apiary Constitutions is a tool to write API Design Style Guide rules locally (API Blueprint, OpeAPI/Swagger, … code snippets) and test them in CI.

Apiary Constitutions repository

How to write an API Design Style Guide

1. Prepare the Style Guide conceptually

  • Catch the idea
  • Create a written free-form verbal documentation, formal specification, white paper etc..
  • Collect all the PDFs, Google Docs, Markdowns, READMEs, rtfs and docs you already have in your drawers

2. Breakdown the specifications into single rules

  • Identify and isolate single rules in the textual styleguide you created on step 1
  • Add good and bad examples for every single new rule using API Description language (OAS/Swagger, API Blueprint, …)

3. Development of the rules

3.1 Install prerequisites

$ npm install

3.2 Create new styleguide rule directory structure and files

Fork this repo

Run:

$ ./scripts/init name-of-your-new-rule-directory

The following structure should be created in /styleguides directory

├ main-rule-dir
│  └examples                                - examples directory
│     ├ bad                                 - bad examples directory
│     │  ├ bad-example1
│     │  │  ├ api-description-document      - API description document that should fail
│     │  │  └ meta.yaml                     - configuration and metadata for the example
│     │  └ bad-example2
│     │     ├ api-description-document
│     │     └ meta.yaml
│     └ good
│        └ good-example1                    - good examples directory
│           ├ api-description-document      - API description document that should pass
│           └ meta.yaml                     - configuration and metadata for the example
├ functions.js                              - validation function definition
├ rule.yaml                                 - rule configuration and metadata
└ README.md                                 - generated readme file (do not edit)

3.3 Write the examples

Write at least one good and one bad API description document.

3.4 Write the validation function

Write the validation function to functions.js

Function must be defined by declaration. Function must be exported by

module.exports = {
  myFunction,
};

Each function has one input parameter - minim element if minim is set to true in rule configuration or (deprecated) JSON object found on desired path in refract tree. Function is not executed if no object is found. The function must return true if validation passes or a string which describes reason of failure if validation fails. You can require npm packages (after installing them to node_modules) or libraries. lodash package is available out of the box. Any I/O are disallowed for security reasons.

3.5 Write the rule configuration

Write the rule configuration to rule.yaml

title: title of this rule
intent: intent/description of this rule
allowedTargets: list of allowed targets
minim: true
functionName: name of the function defined in functions.js file

allowedTargets is list of targets rule can be applied to.

Supported targets
api

meta
title
copy

resourceGroup
resourceGroup.title
resourceGroup.copy

resource
resource.title
resource.copy
resource.href
resource.hrefVariables

transition
transition.title
transition.method
transition.copy
transition.hrefVariables
transition.requestAndResponse

request
request.copy
request.messageBody
request.messageBodySchema
request.headers
request.header

response
response.statusCode
response.copy
response.messageBody
response.messageBodySchema
response.headers
response.header

header

3.5 Write the build configuration

Write the build configuration to ./build/build.yaml

title: styleguide title
description: description of this styleguide
rules:
  - name-of-your-new-rule-directory

3.6 Build and Test

Constitutions test runner

By running

npm run test
  • every rule defined in ./build/build.yaml is tested against its good and bad example
  • README.md file is generated for each rule defined in ./build/build.yaml in its directory
  • compound README.md file is generated to ./build/README.md
  • bundle with all functions and its dependencies defined in ./build/build.yaml is generated to ./build/functions.js
  • ./build/rules.json is generated

rules.json and functions.js bundle can be used for Apiary Styleguides or Apiary CLI

Related topics