first commit of api spec

I think we could use [URL Templates](http://en.wikipedia.org/wiki/URL_Template) in these instances without losing anything.