[BetaMechazawa]

I'm currently working on a libre push notification service (Heavy WIP) and since this post is about API's and Documentation I was wondering if mine is any good.

It requires javascript for the "full experience". https://api.pushjet.io

Should I redo it? Are there things I should change?

[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.

[yourad_io]

I would add a few paragraphs introducing it and giving some common examples/use cases.

I like your "try-this-request", however IMHO it is missing a "request is in progress..." kind of indicator - clear the output space and add a spinner? I had to look in the developer tools to ensure that it works.

Finally, not all things work: 'Websockets/Run Example' doesn't do anything. In the background there is a 500: 'WebSocket connection to 'wss://api.pushjet.io/socket' failed: Error during WebSocket handshake: Unexpected response code: 500'. In your defense, you do mention that "Websockets are really iffy at the the moment and are currently in the process of being redone". But still, better capture that error and show it somehow.

All in all, ahead of the curve ;) Some UI lovin' would put you at the head of it.

[BetaMechazawa]

Thanks a ton! I've always been annoyed by the fact that Web API documentations never had a "try-this-request" feature. I'll get right to expanding the documentation when I get home like I said in the other comments. The request in progress indicator should be pretty easy to add. Totally forgot about it. I disabled the websockets example because It's currently undergoing a complete rewrite.

[diggan]

Looks simple and good to me. However, on first glance, it's missing some quickstart guide/introduction and how to authenticate. Also, some calls seems to return nothing at all, is that correct?

[BetaMechazawa]

I've written a draft for a quick start guide using python/javascript (code with comments). I've been withholding publishing it because it's not fully done yet and message queues and the android app (only thing to do is the Matrial UI) are my #1 priority at the moment. One of the main ideas behind the service is that there is no authentication. You just generate a persistent UUID and use that.