Documentation First: A Recipe for API Success
Why writing your documentation first is an acceptable and effective pattern for developing APIs.
Join the DZone community and get the full member experience.Join For Free
I've shipped a handful of greenfield APIs in recent months for different clients, and in each case I've been building the documentation before the API. I hadn't really recognized it as a pattern until someone else commented on it, but I do find this approach has worked well for my projects, so I thought I'd share my thoughts on this in a bit more detail.
Nailing Down The Big Details
Writing the docs first (I'm using Slate which uses markdown and looks pro from the moment you begin) means having to think about how the first API call, the authentication, the error handling, and so on are all going to work. Writing this down early is a good discipline and can help the thought process if your design isn't completely finished by this point.
Writing Usage Examples
One thing I really like about Slate is that it has a right hand panel for code examples in different languages. Writing these before I implement the API makes me think hard about how the developers consuming the API will really interact with it, and how the responses need to be structured in order to make sense in whichever example language I'm using.
One thing I usually do here is also include a curl example to cover anyone who isn't using one of the chosen example languages. This really helps to widen who can quickly get started from the docs.
Getting Early Feedback
By writing the documentation super early and circulating it to clients or prospective API consumers means getting feedback incredibly early in the loop. If there's an authentication scheme or data format that they have never heard of or won't be able to integrate with easily, this becomes clear really early on.
Having the code samples in place also helps a lot if the developers that will be using this API can be given the docs at this stage. They can feed back on how things look because it's presented in a way that they can quickly and easily relate to. If they have questions, it's possible to adjust either the documentation or the code — which is fine since we didn't start building the API yet so changes at this stage are as cheap as they can be! Finding out that we'd need a variety of output formats, for example, is much easier when the requirement becomes clear at this stage.
Faster Overall Shipping
For two of the APIs, I shipped docs-first because we didn't have TIME to mess about with amendments and whatever once the API was built. One of them was a really tiny API just to feed some features on a related site. I think we wrote the docs in a day and had the rest of the build done in about three days... as rapid development goes, I'd definitely use this tactic again.
Your API isn't finished until the API, the tests and the documentation are all complete. By leading with the documentation, you reduce the cognitive load needed when creating the tests and then the API itself. Also, once the tests are green, there's no hanging around for documentation. You already shipped and "tested" the documentation so we're all ready to go!
Published at DZone with permission of Lorna Mitchell, DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.