Creating an API

A few tips on how to build a well-structured API. » #api #development

A few weeks back, we publicly released the Gauges API . Despite building Gauges from the ground up as an API , it was a lot of work. You really have to cross your t’s and dot your i’s when releasing an API . 1. Document as You Build We made the mistake of documenting after most of the build was done. The problem is documenting sucks. Leaving that pain until the end, when you are excited to release it, makes doing the work twice as hard. Thankfully, we have a closer on our team who powered through it. 2. Be Consistent As we documented the API , we noticed a lot of inconsistencies. For example, in some places we return a hash and in others we returned an array. Upon realizing these issues, we started making some rules. To solve the array/hash issue, we elected that every response should return a hash. This is the most flexible solution going forward. It allows us to inject n...

Full article: http://railstips.org/blog/archives/2011/12/01/creating-an...