I’ve already talked about Tom Johnson’s podcast series I’d Rather Be Writing, where he shares his thoughts and experiences about writing API documentation in the burgeoning San Francisco technology and start-up scene.

On a IRBW podcast, Tom talked with Michael Stowe, who wrote Undisturbed REST: The guide to designing the perfect API.

They introduced the concept of the RESTful API Modeling Langage (RAML), which you can read more about on https://raml.org/

What makes RAML worth considering is that it is actually a full API lifecycle tool. It lets you design your API design without actually coding anything, but also create a fully functional mock for customers, partners, or internal engineers to review and build from.

If used by the whole organisation, you can avoid a lot of technical debt by getting all parties to agree on the design of the API before you task any developers with actually writing the endpoints.

The advantage for documentarians, is that RAML also has our back’s covered. Because documentation is a crucial part of the API lifecycle, writing the spec for the API from the start bascially means that it is documented.

If you are starting out with API technology in your company, consider adopting RAML to control the API lifecycle.