REST API Style Guide

Overview

This is the style guide for the Cadmium API documentation. This guide is designed to help you produce usable documentation for the REST APIs in cadmium, without requiring a lot of work.

What the API documentation should be

The API documentation should be a useful tool for someone writing clients for cadmium. Try to break your documentation down by resource and then tell a narrative about using that resource.

What the API documentation should not be

The API documentation should not be a detailed specification. Documents like that are:

• hard to write
• hard to keep up to date
• hard to use when trying to really get things done.

We should be placing detailed specifications in our automated regression tests. If someone really needs that level of detail, it will be easier to write, update, and consume in that format.