Closed Bug 1158386 Opened 8 years ago Closed 4 years ago

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


(Socorro :: Webapp, task)

Not set


(Not tracked)



(Reporter: kairo, Assigned: willkg)



(1 file)

Every time I try to work with the API, I run into the issue of going to ("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. 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

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
fix bug 1158386: add help text for all public API endpoints
Merge pull request #4785 from willkg/1158386-api-docs

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