109

Method List

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

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)
  • callback=functionname: returns JSON with Padding instead of standard JSON
  • filter={filter}: specifies which fields to return

Site specific methods also take

  • site={sitename}: specifies the site to query against, can be the full domain name or just part
    • for example stackoverflow.com, askubuntu, and gaming are all valid

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.1/usage. Further details may be found in the revision history of this post.

2
  • 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. Feb 10, 2011 at 3:30
  • 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
    Aug 22, 2014 at 3:59

3 Answers 3

16

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}
8

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.

1
  • 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. Jun 10, 2010 at 0:24
2

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.

7
  • 1
    As far as I noticed, all the keys, and values are case insensitive, may be the documention just inconsistence.
    – YOU
    May 28, 2010 at 13:00
  • @SMA - that is a relief. I don't like special cases. May 28, 2010 at 14:04
  • 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. May 28, 2010 at 21:05
  • 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. May 28, 2010 at 21:10
  • @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. May 28, 2010 at 21:19
  • @kevin, r.e. ID - i was commenting on the summary line, which implies a singular, but the id param def is correct. May 28, 2010 at 21:41
  • 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. May 28, 2010 at 22:02

You must log in to answer this question.

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