Closed Bug 1158386 Opened 8 years ago Closed 4 years ago

"API Documentation" is not documenting the expected format of parameters

Categories

(Socorro :: Webapp, task)

task
Not set
normal

Tracking

(Not tracked)

RESOLVED FIXED

People

(Reporter: kairo, Assigned: willkg)

Details

Attachments

(1 file)

Every time I try to work with the API, I run into the issue of going to https://crash-stats.mozilla.com/api/ ("API Documentation") to find out about something, only to find out that it's missing the actual documentation of what format the parameters of the API expect.

Concrete example right now: /api/Bugs/ says to have a "signatures" parameter, which sounds like it could retrieve bugs for multiple signatures, but there is no documentation of how to specify multiple ones.
(Also, in this concrete case, it's confusing as to why the output for e.g. https://crash-stats.mozilla.com/api/Bugs/?signatures=EnterBaseline would return entries of different signatures as well - I'd expect explanations like that at least linked when something calls itself "API Documentation".)
When we're done with our death-to-middleware we should make sure our new API thing works according the points KaiRo makes here.

I think there are two issues here.

First is covered in the description and I think these two cases could be documented:

  1. date/datetime formats
  2. lists of things

Second is covered in comment #1 and that API could use a description of what it's doing.

Grabbing this to work on now.

Assignee: nobody → willkg
Status: NEW → ASSIGNED

I skimmed through the code and looked at things. The date/datetime fields have a date/datetime input, so I think that's fine. You can do a test run which shows exactly what the urls will look like and I think that covers a lot of usability issues.

I'm going to rescope this to adding help text for all the public endpoints that clarify what they do.

Commits pushed to master at https://github.com/mozilla-services/socorro

https://github.com/mozilla-services/socorro/commit/e9f1960ca0971c01ec5b4c1fc5e6914808c0e842
fix bug 1158386: add help text for all public API endpoints

https://github.com/mozilla-services/socorro/commit/3f05e1c7abd6f095fccb86a3af8ad718d0e70a0c
Merge pull request #4785 from willkg/1158386-api-docs

fix bug 1158386: add help text for all public API endpoints
Status: ASSIGNED → RESOLVED
Closed: 4 years ago
Resolution: --- → FIXED
You need to log in before you can comment on or make changes to this bug.