[onion2k]

It's really not even close to being verbose enough. A good API doesn't just give you the name of the endpoint and what it's expecting - it should explain what the endpoint is for. Your documentation assumes the user already knows what they're going to implement in terms of your API (eg they know that they'll need to create a 'service' that other clients will 'listen' on, and so on.

Also, what's especially unhelpful in your documentation is the fact your example code returns errors. In the /listen POST documentation clicking the Send button displays

  {
    "error": {
      "id": 4,
      "message": "Already listening to that service"
    }
  }

I assume that means it's already connected, but should that be the case in an example of creating a connection?

EDIT: My post would be more useful with an example of how verbose I think you should be. Firebase gets it right - https://www.firebase.com/docs/web/quickstart.html - and their brilliant interactive tutorial that really drives home how easy it is to use - https://www.firebase.com/tutorial/#gettingstarted

[BetaMechazawa]

The API documentation is talking to the live version of the application. The pre-filled variables can be used for quick testing but this also means that when you make the default user (UUID) listen to the default service it will tell you that it's already doing that. Changing the UUID should be sufficient to give it a non-error response for that API call.

I'll add some documentation about what endpoints do and what kind of "flow" an application needs to interact with the API when I get home from work. I'll also finish my quick start guide while I'm at it then.