Documenting your APIs

Posted by David Estes on Jun 07, 2015

Filed under Grails, Open Source, Groovy

Last week I had to rush to figure out how best to document some public developer API's for Happy Apps. We had already created some great RESTful OAUTH2 friendly API's for use with our iOS / Apple Watch app release but had not yet worked out how to present these API's to our users and any newcoming users that might want to use them. There are several possible avenues you can take when documenting your API's

Automated API Docs

Some options exist where the syntax of your comments on an API method within your code will auto generate a user friendly api doc. This has a few benefits in that its close to the code in question and therefore less likely to get out of sync. (But we all know people dont review those comment blocks before making changes to the code). In some cases this is great, especially for internal api documentation that the rest of your team can follow. These types of documentation points are more for people who are already very familiar with the code base and infrastructure. I think they definitely have a valid use case but what about the customer facing developer APIS?

Test API Docs

I've also seen solutions where the structure of your API functional tests define the api document. This has the great benefit of validating that your documentation is indeed working perfectly. Definitely a really cool viable option. I have not seen a solution for this for the Grails framework yet but I have for RSpec and Rails. It is called rspec-api. Unfortunately this is not a viable option for me here but definitely a solid choice when making api documents.

Static API Documentation

A friend recommended I try a static page generator called slate. This library allows one to write their API documentation in Markdown and automatically generates an elegant mobile friendly single page UI complete with code samples. You simply fork this repository and you can easily get started. Why is this better than keeping the API in your code or via tests? It has a few great advantages actually. One is you can make this repository public allowing your customers/users to help notify you of issues with the documentation you might not have thought of. All the while your application code can stay private. The other nice thing about this elegant solution is the generator stays out of your way allowing you to just focus on writing up examples and iterate quickly without having to worry about long build times on your application. If you have some API documentation you have been itching to do I strongly urge you to check out slate.

With that all being said I can now release the Happy Apps API Documentation that fully drives the iOS version of the service available here. You can even contribute to the documentation in it's github repository. There is definitely some work to still be done but I think this is a great initial release that can demonstrate the power of being able to monitor your infrastructure and services in the cloud without the convoluted nagios configuration and setup.