Why optional attributes will ruin your API Blueprint documentation
I am pretty pleased with our API documentation. I would even go as far as to say smug.
The reason for this? Our APIs are documented using the API Blueprint (.apib) format. It’s machine readable, so not only can you generate docs from it, but you can also test that your docs match your live API. Awesome.
I was flying high, until I got this slack message:
“fyi, the API returned a parameter that wasn’t in the docs”
What happened? I tested the docs again. I looked through the test results and sure enough, there was the extra parameter. Not only that, but the tests were happily passing.
After some debugging with Apiary’s (excellent) support, they linked me to the MSON spec about the Type attribute.
By default, the Type attribute is set to optional. This means that additional parameters in the response are allowed. If you set the Type attribute as fixed-type, any additional parameters will not be allowed. While this isn’t a big deal if you only generate documentation, it makes a world of difference once you start testing it.
I modified my response attributes and ran the tests again.
I’m rarely happy to see tests fail. This time I was overjoyed.
I updated the API descriptions, and was happy to go back to being smug about my perfect documentation.
The moral of the story
For a developer working with your API, nothing is more frustrating than documentation that doesn’t match the actual responses. The Type attribute is critical for Dredd to test whether your API matches your specification exactly. For such an important parameter, I found very little mention of it in the API Blueprint and Dredd documentation.
Dredd correctly claims that it can ‘validate (your) API description document against (the) backend implementation of the API’. But just like any program, it only does what you tell it to do.
You’ve done the work documenting and testing your API. Don’t ruin your documentation. Set your attributes to fixed-type.
