Curse of REST style APIs – Documentation
Making APIs accessible or discoverable are becoming overloaded terms and means different things to different people.
2 different perspectives
The companies which are trying to monetize their APIs may want make it more easy to understand. They want the users to know how to use the API and may be to try it. All these makes sense ONLY to them. For instance if we take Google maps – The documentation along with samples clearly tells to use it, google also provides a API explorer for the trying it out. But for enterprises who are trying just to clearly document APIs and make it more re-usable have a similar but a subtly different problem to solve.
If you have seen the google documentation sited above – it is a webpage describing each and every attribute of the API with long descriptions and so on. That is a lot of manual effort. Enterprises may not spend so much time and effort in updating the documentation simply for the reason that it is NOT getting them money directly or will NOT destroy their reputation if the documentation isn’t up-to- date. So we need to strike a balance here and produce a decent (not like google’s) documentation by harvesting details from the API itself and update it with minimal effort as the API gets revised/updated. Most certainly we don’t need a “try-out” option provided in this case. But from the programmers side some effort is required to support the documentation harvesting systems.
It basically boils down to 2 options.
- Writing documentations using some standards independent of code
- Annotating the code to generate documentation using some frameworks while deploying the APIs
1. Independent documentation
2. Annotative frameworks for documentation harvesting from code – there are lots out there , here is my comparison on a few which gets lot of attention.
Do you have a better way to document RESTful APIs ?