REST API Style Guide

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 Should be Documented

For each resource in the API, the structure of the representations for that resource should be documented, as well as all of the methods that use that representation. In general, try to focus on information that is useful to clients of the API.

What Should not be Documented

Do not provided so much detail that the documentation becomes a detailed specification. We should point people at the automated regression tests for that level of detail.

Formatting Server Requests and Responses

Try to capture request and response pairs in your documentation with the following format:

METHOD PATH
> REQUEST HEADERS
REQUEST BODY (optional)
< STATUS
< RESPONSE HEADERS
RESPONSE BODY

Focus on the information in these pairs that is useful in the context of the document.

Dealing with Cross Cutting Concerns

Documentation for cross cutting concerns (like authentication) should be in a single document. Documentation for resources should link into that document, when applicable.