4

Right now the documentation is pretty terribly organized. For example, consider the things under the "Users" heading:

  • /users => returns Users
  • /users/{ids} => returns Users
  • /users/{ids}/answers => returns Answers
  • /users/{ids}/badges => returns Badges
  • /users/{ids}/comments => returns Comments
  • /users/{ids}/comments/{toid} => returns Comments
  • /users/{ids}/favorites => returns Questions
  • /users/{ids}/mentioned => returns Comments
  • /users/{id}/privileges => returns Privileges
  • /users/{ids}/questions => returns Questions
  • /users/{ids}/questions/no-answers => returns Questions
  • /users/{ids}/questions/unaccepted => returns Questions
  • /users/{ids}/questions/unanswered => returns Questions
  • /users/{ids}/reputation => returns Reputations
  • /users/{ids}/suggested-edits => returns Suggested Edits
  • /users/{ids}/tags => returns Tags
  • /users/{id}/tags/{tags}/top-answers => returns Answers
  • /users/{id}/tags/{tags}/top-questions => returns Questions
  • /users/{ids}/timeline => returns User Timeline
  • /users/{id}/top-answer-tags => returns Top Tags
  • /users/{id}/top-question-tags => returns Top Tags
  • /users/moderators => returns Users
  • /users/moderators/elected => returns Users
  • /users/{id}/inbox => returns Inbox Items
  • /users/{id}/inbox/unread => returns Inbox Items

Under this single heading, there are 12 different return types. In fact, the only thing these methods seem to have in common is that the path starts with "/users", because not all of them even take user ids.

So: can we please get a more sane organization of the documentation page? Something like this would be AWESOME:

Things that produce Users:

  • /users
  • /users/{user ids}
  • /users/moderators
  • /users/moderators/elected
  • /tags/{tag}/top-answerers/{period}
  • /tags/{tag}/top-askers/{period}

Things that produce Answers:

  • /users/{user ids}/answers
  • /users/{user id}/tags/top-answers
  • /answers
  • /answers/{answer ids}
  • /questions/{question ids}/answers
  • ...

Things that produce Questions:

  • /users/{user ids}/favorites
  • /users/{user ids}/questions/no-answers
  • /users/{user ids}/questions/unaccepted
  • /users/{user ids}/questions/unanswered
  • /users/{user id}/tags/{tags}/top-questions
  • ...

... etc

Organizing things by what they return and not (seemingly) what the first part of their endpoint path is would make things much easier to find.

3
  • 4
    And to emphasize how much I think this should be done, I will gladly put up the maximum bounty if people need convincing. Jan 2, 2012 at 18:29
  • 4
    +1 a list of types would be nice as well (without having to go into the method page)
    – Jonathan.
    Jan 2, 2012 at 19:20
  • 1
    Hooray for status-planned!!! Jan 4, 2012 at 0:08

2 Answers 2

1

... sort of. I'm still planning on putting something fancy on /docs/types (there's nothing there now) but haven't quite worked out what yet.

Anyhoo, the main /docs page now has tabs

enter image description here

which change how methods are grouped.

"by category" returns methods as they always have been (by site / non-site, then by "what you're thinking about" [give me answers, give me answer comments, etc.]). "by type" groups by "top level types" (things actually returned by methods) and then by the actual type returned (listing "member types" that aren't returned by any method directly separately).

1

OK, I've just discovered that at the bottom of each "type" page, there's a list with this information. For example: https://api.stackexchange.com/docs/types/user#methods This is insanely useful. But it's in a hard-to-find location, especially since there isn't a comprehensive list of types anywhere.

1
  • 2
    It would be much better to have it on one page like you suggested.
    – Jonathan.
    Jan 2, 2012 at 23:57

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .