clarify comments
add API spec to README
Merge pull request #12 from GabeMedrash/master

add API spec to readme