Should there be a discovery API?

Question

It would seem to me that a simple API that return an array of the API base URL and perhaps the common name of the sites that support the API would be valuable. Is this sensible?

EDIT:

This is what I want:

{
  "api" : [
    { "endpoint" : "api.stackoverflow.com",
      "name" : "StackOverflow"},
    { "endpoint" : "api.meta.stackoverflow.com",
      "name" : "Meta"},
    { "endpoint" : "api.SuperUser.com",
      "name" : "SuperUser"},
    { "endpoint" : "api.bobsyouruncle.com",
      "name" : "Bob's your Uncle SE"}
   ]
}

Answer 1

I agree that there needs to be a way to discover API endpoints. Especially with the brave new world of SE 2.0 potentially leading to an ever increasing number of API-ified sites out there.

However, there isn't a good place to shove this functionality just yet.

Currently, we only have two places it could go:

• api.[stackoverflow|superuser|serverfault|meta.stackoverflow].com
  • not "global," and accordingly shouldn't know about all the other sites in the network
• api.stackapps.com
  • more "global," than the above, but also a site onto itself; it'd be a weird one-off to also have it serve up a network map

A similar problem exists with getting user associated accounts.

In short, once there is a place for this data to come from it'll be made available. Most likely, this will exist "out of band" from the regular API.

---

See StackAuth - /sites route - for endpoint discovery.

Answer 2

This is important if you want to be able to build an app that supports all available sites. Right now there are only a few, but eventually the list will grow and simply adding entries by hand will become too difficult. There also was a similar request for discovering what versions of the API are available.

The tricky part is that the methods would not really fit well on the API for any of the real "content" sites, but instead would be a better fit for a special StackExchange API or a StackApps API. Any /Sites or /Versions methods could then be separated from the general API methods that are accessible from the content sites APIs.

In the future there could be other app-specific methods that are added such as key management or retrieving stats for your application (unique IPs, request count, etc). These all should be grouped in one place, which doesn't really have a home right now.

I think the best thing to do right now is to setup your App to bind to a hard coded JSON object that you create so that you are ready once such a method is available. Also some of the API Library and Wrappers already try and help manage the available sites to query, currently using hard coded enumerators but eventual could bind to an API method.

Answer 3

Kevin hinted at something like this when I was discussing making a FUSE (file system in userspace) implementation of the API on dev.meta.

It would work like this, assuming you had the file system mounted on /stacks :

cat /stacks/stackoverflow.com/users/1/reputation

... You'd see Jeff's reputation. The problem is (and was) is that I'd need to be able to discover all API methods to organize and set up the FS hierarchy, which means some method to discover all available methods and hints as to what they return.

The particular question went to radio silence, I'm not sure if something like that made it into the current beta, but I hope it does :) A FUSE implementation would let lots and lots of languages for where no API bindings exist access the API rather easily.

Edit

There is a help option , but its not quite convenient to parse.