API v1 spec

This is still a work-in-progress, but any feedback is more than welcome.
And you can implement this as an opaque thing that is structured internally: http://play.golang.org/p/twMCE4J-ES