API Documentation Can’t [Yet] Document APIs
Search. The final frontier. At least for RESTful Web API documentation. And that’s really unfortunate because as the industry realizes APIs are as vital to our systems as HTML, the shortcomings in API documentation are forcing some bad choices:
- Only describe CRUD operations in your API documentation, leaving the R[ead] to be for singletons & have full search outside of the tooling doc
- Under-document your search services, showing only your most used parameters in the documentation
- Bastardize the API to meet the constraints of the documentation (e.g., forcing everything into a q parameter)
This problem came up for me, again, when trying to setup best practices for an API sample codebase we’re going to open source at work — an API to help students learn to consume and create their own services. I’ve been stalling its release for months because I wanted to release it with full Open API documentation to describe its entire functionality. It isn’t even that fancy, just searching filters like:
- Products updated between date X and Y
- Products less then $Z
- Products in category alpha, bravo or charlie
- Products containing the word phone, but excluding the word case
As I said, there’s nothing magical about it — but in months of reading the many GitHub repos for the main API documentation providers, all you find is years of bickering about “best practices” and “what Tim Berners-Lee wanted” and “just fork your own”. The end result is we’re all making the above bad choices or worst-yet not documenting our APIs while we wait for a new spec. You can see this choice throughout the industry, for example Expedia’s fantastic Swagger doc has 25% of the search functionality as its website & mobile apps. Core members of the Open API Initiative, at least those who make their swagger.jsons public, also avoid capturing the non-trivial parts of their functionality.
If we can’t document our most commonly used features, we’re bike-shedding and waiting time.
So what’s the call to action? Well I think there are a couple:
- We need a few less petshops and a lot more real world examples
- We need to decide if {json:api} is our future
- We need an independent solution to measure spec coverage, much like CSS has Acid Tests
- We need more various API spec documentation providers to say “Here is an existing popular API, and here is how our system can document it”
- We need to call out these foundations when they refuse, for years, to provide realistic solutions
We all want better documentation. And we want to know that if we’re investing our companies and ourselves in using these tooling solutions, we’re not short-changing our own solutions in exchange.
Help us, Open API Initiative and RAML and API Blueprint, you’re our only hope.
