(TK-117) Add external API docs

Add some external API docs in the doc folder which detail how
to make requests using the Java and clojure clients.
I think "defaults to true" should be left out here since it the caller is explicitly required to provide a value.