REST API Documentation

I recently had the opportunity to write a short (about 10 page) manual on a specific REST API for a client. I’m still trying to find some spare time to edit out any confidential info so I can post a PDF, but hope to get that done this week.

REST API documentation is a growing area for technical writers. I’ve documented specifications before, and have documented software that used calls similar to REST to perform operations. But one thing struck me immediately about the sample docs I was finding online that were specifically REST API docs: they jump right in to tables of parameters. I saw almost zero text of the type I call hand-holding (aka guiding a newbie over to the swimming pool before throwing them in) and very little orientation (pointing out which part is the deep end, or where they need to swim to to get out, to use the same metaphor). And I just couldn’t do that to my audience.

My document has tables of parameters and values, but it begins with a “getting started” type of section to lead the reader to the pool, and has tips and introductory paragraphs throughout to orient the reader. It may not be the standard style for REST API docs (many of which are written by engineers and not just for engineers), but it felt like the right thing for my doc, since the audience includes managers and not just engineers.