Posted on 03-08-2012
This post comes from the SDK Bridge newsletter. I find so much value from what Peter and Jonathan do over at SDK Bridge, I always have to post their newsletter here and share with all of you.
People are constantly trying to come up with tools to make API documentation an easier task. If you are documenting an SDK built for C++, C#, or Java, there are tools such as Doxygen, Sandcastle, and JavaDocs to take comments from the code and automatically generate documentation from them. Why aren't there tools like this for REST APIs?
The beauty of Web APIs is that they can be written in whatever language you like and in whatever manner you like. As long as when an HTTP request comes in, the proper HTTP response goes out, it doesn't matter how it actually happens on the server. But this very flexibility makes automated documentation nearly impossible, since there's no standard mapping between what an API request is and what the code is that generates its response.
Nonetheless, there are some solutions out there to this problem. I need to start by saying that there are in fact two approaches to automation that are used to document REST APIs. One is similar to the tools I mentioned above, where comments are taken from code to generate the documentation. The other involves having the documentation separate from the code, but in a data format (such as JSON) that can be parsed and used to generate the documentation.
I also should mention that documentation automation does not guarantee good documentation. Before choosing to to incorporate automation into your process, I recommend reading an excellent article by Dana Fujikawa: What to Consider Before Considering Auto-Generated Documentation.
Automated Documentation from Code
There's no off-the-shelf tool that pulls documentation comments out of code that's going to work for all REST APIs. But there are two possible solutions:
- Use a framework that both generates the APIs and the documentation
- Create methods with a one-to-one mapping with API requests.
Framework. A good example of a REST API framework is Enunciate. Enunciate is an open-source Java-based Web API framework. It creates full HTML documentation of the services it generates, where the documentation is assembled from JavaDocs comments.
Mapping. Mapping requires some disciplined practices, but has the advantage that it can be used with any technology. In this case, you need to create public methods that map directly to API requests. So, for example, you might have an API request to get a brief user profile for a user with an ID of 23423 with a call like this:
When this request comes in, you need to structure your code so that it calls a method by the name of something like:
public get_users__id__profile(int id, string profile_type)
Note that the
id is surrounded by double underlines, indicating that it is not literally the text "id".
This method would then have comments that could be picked up by automated tool, such as JavaDoc, RDoc, or Sandcastle, and HTML documentation would be generated. Then you would need to run the HTML documentation through an automated process that would remove unnecessary information (such as class names), and convert the method names, replacing single underlines with slashes and double underlines with slashes and brackets so that
The parameters table would also need some modification so that it's clear which parameters are part of the URL and which are query parameters.
It's not a simple process, but I have seen it done successfully using Ruby code and RDoc.
Automated Documentation from Structured Data
The advantage of taking comments from code is that if there are changes in the code, the comments are more likely to be updated. However, a simpler and very flexible solution is to have the documentation in structured data (JSON or XML), and then have an automated process create the actual HTML documentation from it. There are a several tools that will do this, merging documentation with an ability to try out the REST calls, which is extremely handy. Here are some examples.
Swagger. Swagger is a tool created by Worknik that creates very nice looking API documentation with the ability to easily try any API request. You specify a resource discovery URL which returns JSON with information about the various REST resources, then for each resource, you specify the type of operation, the path, the potential errors, and the response. Although you are limited in how long your descriptions can be, it creates a very nice documentation system for straight-forward APIs.
Create your own. If neither of these tools are flexible enough for your API, you can create your own. A beautiful implementation that I had the priviledge to work on was created by Tendril. Take a look at an example API request at Cost and Consumption for a Single Device. You can see how you can try it out on the first tab, but then other tabs list parameters, response, and notes. By creating their own system, they were able to document a fairly complex API call which would not have worked with an off-the-shelf system.
Automated REST API documentation can be used to:
- Keep the documentation near the code so that it's easier to update.
- Allow developers to try out of the API requests as part of the documentation.
Although it is impossible to have a tool that automatically generates REST API documentation from any code, there are a number of approaches that will let you autogenerate the documentation, including:
- Using a framework that generates both the API code and its documentation.
- Creating a mapping between methods and API requests and using standard documentation tools.
- Writing documentation as structured data and generating HTML from it.
comments powered by Disqus
Winning in the API Economy
|Download as PDF|
Latest Blog Posts
- Thank You @3Scale For Investing In The Community With @APIStrat
- Introducing API.Report, A Community API News Site
- Extract Knowledge From Audio And Video Using The Clarify API
- My API 101 Workshop At @APIStrat In Chicago Next Week
- Some Advice For The Enterprise When Beginning Your API Journey
- Machine Readable API Definition Format Swagger Matures to 2.0
- How Do We Continue Moving Green Button Data And APIs Forward?
- Beyond Public APIs In Government: Internal Access to Resources
- Can You Show Me The ROI On All Of This API Stuff Before We Commit
- In The Future APIs Will Be Default For All Cities
- No Public APIs Are Not Going Away Just Cause A Few BigCos Fumble At It
- Internal API Search Engine For Everyone At Your Company (Not Just Developers)
- If You Need Assistance With Your Healthcare API Strategy I Have The Person
- Explaining APIs To Senior Leadership: Access To Company Resources Without The IT Hassle
- A Conversation With @ijroth, @dorkitude, @antonyfalco, and @medjawii In The Next Generation API Stack Panel @APIStrat
- API Evangelist Thoughts On The Right To An API Key And Algorithmic Organizing
- Explaining APIs To Your Senior Leadership
- An API Evangelism Strategy To Map The Global Family Tree
- Thank You For Your API Evangelist Blog(s)
- Video From The Hypermedia Panel At API-Craft In Detroit Last Month
- Please Open Source Your API Before Shutting It Down
- Explaining My Work Around APIs In Higher Education To Institutions
- You Can Have An API Just By Choosing Products And Services That Have APIs
- Using Excel As An API Datasource And An API Client For The Masses
- Brewing Up Something Awesome With The Jive Software API