986421 - Need clear documentation of the server APIs

Status: VERIFIED FIXED

(Hello (Loop) :: Server, defect)

Description

[Mark Banner (:standard8)]

The server API documentation is highly insufficient. I currently have the following issues:

- Some requests require parameters in JSON bodies, others require them in querystrings
- It is unclear the intention of some of the parameters, and what their intended values and scales are.
- The return values are not documented.

The API documentation really should be updated in sync with the bugs that are implementing/changing the APIs.

Comment 1

[Dan Mosedale (:dmosedale, :dmose)]

Should reviewers be requiring documentation updates for r+?  I'd say yes.

Comment 2

[Rémy Hubscher (:natim)]

dmose we will definitly do that in the future.
The hardest part is to setup the first layout.
Tomorrow we will land the first documentation draft and after that we will require documentation changes for every PR. :)

Comment 3

[Dan Mosedale (:dmosedale, :dmose)]

Great; glad to hear it!

Comment 4

[Alexis Metaireau (:alexis)]

Attachment: link to github PR

Comment 5

[Alexis Metaireau (:alexis)]

I did a pull request with some basic documentation. Please provide me any feedback on it. You can have a look at the rendered documentation here, in the meantime I put a preview version here: http://alexis.notmyidea.org/services-docs/loop/

Comment 6

[James Bonacci [:jbonacci]]

+1 because QA loves documentation.

Comment 7

[Rémy Hubscher (:natim)]

In my experience it helps to give curl example for API calls.

Comment 8

[Rémy Hubscher (:natim)]

Maybe using the HTTPie <https://github.com/jkbr/httpie> format?

Comment 9

[Alexis Metaireau (:alexis)]

That's a brilliant idea! I've updated the docs with full examples. Updated the temporary location : http://alexis.notmyidea.org/services-docs/loop/apis.html#apis

Comment 10

[Mark Banner (:standard8)]

Comment on attachment 8396763 [details] [review]
link to github PR

Commented on PR, looks generally good to me.

Comment 11

[Nicolas Perriault (:NiKo`) — needinfo me if you need my attention]

Comment on attachment 8396763 [details] [review]
link to github PR

Looks very good to me as well.

Comment 12

[Dan Mosedale (:dmosedale, :dmose)]

Comment on attachment 8396763 [details] [review]
link to github PR

Looks good to me too.  Presumably, this wants to be linked to from the wiki page and the README once it's live.

Comment 13

[Adam Roach [:abr]]

Comment on attachment 8396763 [details] [review]
link to github PR

This looks correct for MLP. Thanks.

Comment 14

[Alexis Metaireau (:alexis)]

Waiting for the docs to regenerate. In the meantime they're available here: http://moz-services-docs.readthedocs.org/en/latest/

Comment 15

[Maire Reavy [:mreavy]]

Alexis -- Is this bug completed for MLP?  Thanks.

Comment 16

[Alexis Metaireau (:alexis)]

For whatever reason the docs fails to generate, that's why I'm keeping it open.

Dan, can you have a look there and tell me why the docs are not generating correctly on docs.services.mozilla.com ? (the svn seems up to date, but the actual docs aren't).

Comment 17

[Daniel Maher [:phrawzty]]

It should be noted that I no longer work in the webops team, and thus, am no longer responsible for this mechanism.

That said, I looked into it, and determined that the cause of the problem was a simple logic failure in the update script, which would cause it to not pull the repo under a specific circumstance.  That has now been fixed, so the site should update as expected from now own.  I apologise for the inconvenience.

Comment 18

[Alexis Metaireau (:alexis)]

Oh okay, thanks dan for the convenience then ;)

Comment 19

[Alexis Metaireau (:alexis)]

http://docs.services.mozilla.com/loop/apis.html is the new docs location.

Comment 20

[James Bonacci [:jbonacci]]

Yep.