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.

2 Answers
2

status-completed... 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

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

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.