share
Stack AppsAPI Documentation and Help
[+99] [3] Kevin Montrose
[2010-05-19 21:31:53]
[ discussion faq getting-started help ]
[ http://stackapps.com/questions/1/api-documentation-and-help ]

Method List

All API methods can be found at https://api.stackexchange.com/docs.

Global Method Parameters

All methods accept the following parameters:

Site specific methods also take

Supported Sites

Every site in the Stack Exchange network [3] supports the API, with the exceptions of stackexchange.com [4], and Area 51 [5].

Deprecated Help

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

(1) what about the link on the sidebar that points to this help? Is it disappeared? - systempuntoout
(2) @systempuntoout - it will be back tonight. - Kevin Montrose
Can we have the current version of API mentioned somewhere? I suppose it's 1.0 now, but there's no way to be certain. - Nikita Rybak
Awesome. Thanks for the update! - Diago
Where is the "documentation" ? The link above connects to a page of "example" links. Where is the source code / methods for those examples ? .. I.e. how to send "/answers". - mstram
[+13] [2010-05-30 12:56:00] Sky Sanders

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}

1
[+7] [2010-06-01 15:36:30] slf

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.

[1] http://json-schema.org/

(4) ++ this is a great suggestion. I rolled my own schema on the fly when building stackapps.com/questions/630/…. I am going to consider redesigning the whole SOAPI ecosystem with JSON-Schema in mind, if Keven indicates that there is no intention on their side to do so. - Sky Sanders
2
[+1] [2010-05-28 12:55:17] Sky Sanders

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.


(1) As far as I noticed, all the keys, and values are case insensitive, may be the documention just inconsistence. - YOU
@SMA - that is a relief. I don't like special cases. - Sky Sanders
toDate & fromDate are incorrect, they will be fixed later today. id is a bit odd, I'll admit. The name should actually be something like id(s), but that obviously won't work. Plus, its never passed as an actual parameter (always implicitly, via the path); I don't really think it merits changing. - Kevin Montrose
Also, badges/name was an oversight. Shortly, badges will return all badges, while badges/name and badges/tags will return strictly named and tag-based badges respectively. - Kevin Montrose
@kevin - yes, id(s) is a path component and not an argument. I am just keeping track of the peccadillo as I bit by bit the api. - Sky Sanders
@kevin, r.e. ID - i was commenting on the summary line, which implies a singular, but the id param def is correct. - Sky Sanders
Ah, I see; those are all holdovers from when {id} was, in fact, a singular field. Those should be fixed at the next code push as well. - Kevin Montrose
3