Documentation First: A Recipe for API Success
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 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!
Thx Lorna for sharing. I agree on most of your points an I experienced the same. We are using Apiary. Have you used that too? What I like about using it is that it already creates a test url to use it just from the docs. This makes it easy for our FE guys to start early.
One downside I’ve seen is obvious. Writing docs is not the same as building the api. I ran into several occasions where I needed to change something because it didn’t work out as I aspected it. These changes are not that easy. But guess is the price you get. Still better than the other approaches. Cheers
We’re using RAML (structure) + Json Schema (JSON endpoints) to document our APIs. It makes it easier to write a schema because you can validate examples against it, and also allows us to use the schema to validate requests and responses in Behat tests. We’re also starting to use the schema to validate endpoint inputs.
I think a well-structured, machine-readable schema is a great tool. And you can generate HTML documentation from it too, although we haven’t used that option yet (all our APIs are currently internal).