Stack Apps is a question and answer site for apps, scripts, and development with the Stack Exchange API. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

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.

share|improve this question
And to emphasize how much I think this should be done, I will gladly put up the maximum bounty if people need convincing. – Dave DeLong Jan 2 '12 at 18:29
+1 I had to produce this type of table myself when working on Stack.PHP. – Nathan Osman Jan 2 '12 at 19:16
+1 a list of types would be nice as well (without having to go into the method page) – Jonathan. Jan 2 '12 at 19:20
Hooray for status-planned!!! – Dave DeLong Jan 4 '12 at 0:08
up vote 1 down vote accepted

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

share|improve this answer

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

share|improve this answer
It would be much better to have it on one page like you suggested. – Jonathan. Jan 2 '12 at 23:57

You must log in to answer this question.

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