12

The /sites method is used to enumerate all sites in the network. If your [app] is meant to run against more than a single site (and many are) this method is how you should be discovering new sites in the network.

As there's been some confusion about how this method is meant to be used, I've written this to help make sure you're "doing it right."

/sites returns the following data for each site:

  • Name
  • Url
  • Logo Url
  • Icon Url (158x158; any "web" image format)
  • Api Url
  • Short Description
  • Its State
  • Some Minor Style Information
  • A List Of Old Urls (under the name aliases)
    • Currently no sites return any aliases, this will change in the future

For Stack Overflow the returned object currently looks like this:

{
  "name": "Stack Overflow",
  "logo_url": "http://sstatic.net/stackoverflow/img/logo.png",
  "api_endpoint": "http://api.stackoverflow.com",
  "site_url": "http://stackoverflow.com",
  "description": "Q&A for professional and enthusiast programmers",
  "icon_url": "http://sstatic.net/stackoverflow/img/apple-touch-icon.png",
  "state": "normal",
  "styling": {
    "link_color": "#0077CC",
    "tag_foreground_color": "#3E6D8E",
    "tag_background_color": "#E0EAF1"
  }
}

state can be one of normal, closed_beta, open_beta, or linked_meta. Normal is a fully functional site, with its own domain and styling. Closed and open betas are provisional sites, which may be shutdown should they fail to achieve critical mass; they differ only in that closed_beta sites only allow participation by users who committed to them on Area 51. A linked_meta site inherits user accounts (including reputation) from a parent site; their parent can be inferred by removing "meta." from its domain name.

There is no ordering (implied or otherwise) of the objects returned by /sites, your [app] should enforce any rules w.r.t ordering before presenting this data to the user.

All Returned Values Can Change

While rare (occurring once during the lifetimes of most sites), all values in a site object are fluid. The only constraint is as follows:

If a site has ever legitimately gone under a Url, and that Url is not its current one, it will appear in aliases

For most [app]s this shouldn't be relevant, as if you have a cached copy of a sites data and you find that it has become invalid (the api_endpoint returning 3xx errors) you can simply re-query /sites and continue normally.

Maintain Site References Over Time

If you have cached content keyed or otherwise related to an old site context, you can use the values in aliases to determine which site now corresponds to the old site context. This means you must keep the site_url around for cached site content, a site's name is not sufficient.

Conceptually, this is basically saying that there is a many to one relationship between the urls (ie. aliases) a site has used and the data for the site itself.

To help clarify, the following (pseudo-)code will build a Dictionary which can be used to lookup a sites data given its url, even if that url comes from a cache.

// Let sites be a Site[] where Site is a naive impl of the /sites return
var siteLookup = new Dictionary<string, Site>();

foreach(var site in sites)
{
  siteLookup[site.site_url] = site;
  foreach(var alias in site.aliases)
    siteLookup[alias] = site;
}

// siteLookup is now the aforementioned Dictionary

Caveats

By "legitimately gone under" I mean was not the result of an error or misconfiguration and was the primary url (ie. was at some point a site_url returned as part of /sites). Some sites have redirects from similar domains, these urls will not appear in aliases as they are not considered "primary".

These constraints only apply from the time the API was released. While StackOverflow, ServerFault, and others have gone under different urls in the distant past those will not be in aliases.

When an API endpoint responds with any 3xx error, there is no guarantee that the payload of the response will contain an equivalent API call on the new endpoint.

Common Questions

Why not return a site_key or similar?

There is currently no concept* of a site_key in the SO code base. The idea itself is fraught with problems (consider how catastrophic it would be for two sites to get the same "id" while running under different names), but the basic reason is its lack of existence.

Common suggestions for keys are things like (or equivalent to) a database row number or a resource name (like "mso", "so", et. al used to be). Neither of these have been unchanging even over the course of the APIs development, much less over the lifetimes of the sites. Their unsuitability is demonstrated by the facts on the ground in addition to the above concerns about fragility.

How often should I query for new sites?

/sites can be expected to change no more frequently than once a day, under normal circumstances. If you encounter data that makes it appear that a site has changed, a new site has been added, or an old site has been deleted you should re-query /sites immediately.

Given that /sites is so comparatively static, most [app]s should strongly consider caching it if possible.

Is old /sites data available?

No, and intentionally so (outside of aliases). The current state of the sites is what should be presented to users; old names, descriptions, etc. have been disregarded for a reason, and an [app] should reflect that.

* Where this concept equates to "a value that will not change, ever, for the site"

3
  • Ya, I cache the /sites method for one day. I have a cron job that refreshes the data. Jul 26, 2010 at 4:40
  • +1 thank you for this guide. Could you please elaborate a little bit on 3xx part? Which 3xx status code will you provide? Can't we rely on 302 redirect before refreshing our cache? Jul 27, 2010 at 15:28
  • @systempuntoout - no, you will receive a 3xx error for which the proper response is to refetch /sites and restart the query from scratch. There will be no pointer to the new domain in the response. Jul 27, 2010 at 19:16

1 Answer 1

3

Thanks for wrapping that up (+1) - a couple of recent topics are missing though, so here are

More Common Questions

Why is there no stable sort order for /sites?

See How to order /sites result in a user friendly way to use it in our apps. for comments, discussion and workarounds.

Why is the site creation date not available?

See Can we add a creation_date to the /sites method? for discussion and workarounds.

Are there any high resolution/scalable (SVG) icons or images available?

Right now there are SVG versions available for the non Stack Exchange 2.0 sites only, see the respective question. Others will likely be added over time once the respective communities haven agreed on something (see area51 + logo for more questions regarding this eventually).

Why are the SVG versions not hosted officially and linked via /sites too?

The respective feature-request has not been acknowledged so far by the Stack Exchange team.


For reference and transparency here are links related to questions already included in

Common Questions

Why not return a site_key or similar?

See the declined feature-request please add a key fields to stackauth results for a discussion.

How often should I query for new sites?

See the deferred feature-request Why does the API lack (proper) HTTP cache control headers? for a related discussion.

0

You must log in to answer this question.

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