Here's an API document I wrote.[1] Comments? You asked, so: The organization can be better. Usually when I am looking at an API, the first question I have is,

Here's an API document I wrote.[1] Comments? You asked, so: The organization can be better. Usually when I am looking at an API, the first question I have is, "What is this API, what can I do with it?" There's one sentence about that in the header, but it's not very clear. Then you jump right into low-level protocol details. Your pictures are good, and help to understand, but they come way late. The broad organization should be something like: 1 "Here's what you can do with this API" 2 "Here's how to use it" 3 "Here are the fine details" and maybe (4 "Legal garbage") Nice quote at the bottom.