Regarding paged results:

The API's handling of empty paged results seems inconsistent. Some methods return empty sets, some throw a 404.

It is my opinion that an empty set should be returned for any result that is paged and a 404 should be returned when a specific, singular resource is not found (the number of these methods seems to be shrinking).

Having inconsistent handling makes writing code against the API much more tedious than it needs to be, what with having to keep track of which methods play well with others and which just need to be different. ;-)

I think this is a fairly significant concern.

paged routes that throw when empty

• /answers/{id}
• /comments/{id}
• /questions/{id}
• /users/{id}

I think we should provide a JSON-Schema ^[1] style description instead of or in addition to the current ?help syntax. This would make it much easier to consume, and comply to at least somewhat of a proposed standard.

Issues:

The revisions routes' date keys diverge from the established naming convention.

e.g. all other routes use todate and fromdate whereas the revisions use toDate and fromDate.

Are keys case sensitive? If so, could this be addressed? I am building a wrapper and this single exception gives me a rash.

for badges/name, name seems to be vestigal.

answers/{id} implies that id is singular where as a vector is accepted

revisions/{id}/{revisionguid} - case mismatch between route and definition, revisionguid != revisionGuid

/users/{id}/tags - id is not listed in parameters

For reference: I am writing a self-generating API wrapper for the self-documenting API in the interest of not having to manually test every route and method upon new releases. Simply regenerate and run tests and/or diff to find API changes.