add spec and link to spec in README

Clarified some of the README and transferred the spec back to markdown.
All future changes to the spec will be accompanied by a changelog note.
Lets put ticks around the endpoints?