API Documentation and Help

Question

Method List

All API methods can be found at http://api.stackoverflow.com/1.1/usage.

Global Method Parameters

All methods accept the following parameters:

• type=jsontext: responds with mime-type text/json.
• key={key}: validates this request to a specific application. (More here)
• jsonp=functionname: returns JSON with Padding instead of standard JSON

Supported Sites

Every site in the Stack Exchange network supports the API, with the exceptions of stackexchange.com, and Area 51.

Deprecated Help

Old help methods can be found at http://api.stackoverflow.com/1.0/help. Further details may be found in the revision history of this post.

Answer 1

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}

Answer 2

I think we should provide a JSON-Schema 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.

Answer 3

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.