Sign up ×
Stack Apps is a question and answer site for apps, scripts, and development with the Stack Exchange API. It's 100% free, no registration required.

As work has progressed on the upcoming second version of our API, we've come to a bit of an impasse that's going to force a semi-radical change.

Here's the root of the issue:

  • once you've gotten an auth token over OAuth, you've got a password equivalent-ish (closer in > 2.0) token
  • naturally, all communication with that token needs to go over HTTPS
  • we have a bajillion different domains on the Stack Exchange network
  • the # of certs necessary to cover our existing API endpoint scheme is untenable

Of course, even in a best case we'd have distinct certs for stackoverflow, superuser, serverfault, askubuntu, stackexchange, and stackauth.

We've got a couple options:

  1. bite the bullet, and live with needing a few hundred certificates down the line
  2. move everything under using a header to select the site
  3. likewise, but embed the site in the path as in
  4. again, but use a query string as in

Option #1 is immediately out, our system administrators would kill me in cold blood. Of the three tractable solutions, I'm inclined to go with #4.

My rational is: lots of developers do quick queries against web APIs from a browser, and there's no easy way to slap a header onto a request; so #2 would increase development difficulty. Coupled with some frameworks restricting access to headers, I'm strongly disinclined to persue #2.

The difference between #3 and #4 is largely aesthetic. Our use of vectorized parameters makes for some very large paths already, and we have to make some special tweaks to our stack to handle such large paths; embedded a host in there would require some extra work on our end.

This will have no effect on v1.x

The existing api endpoints would continue to exist, only v2.0 will be affected. Naturally, all subsequent API versions will also live under

A quick progress report

Interally, API v2 has implementions of all existing /questions and /users routes as well as some of the "weirder" methods (like /stats, now known as /info) to demonstrate the robustness of the filter system.

Work has started on authentication, though this certificate issue has greatly slowed progress there.

Accordingly, it is unlikely that we will be ready to enter private beta next week; though we are still on track for a final release this calendar year.

share|improve this question
Would it not be better to use a unique ID for each site, rather than the domain? apple, gaming, wordpress etc? –  nobody Oct 14 '11 at 20:25
@ThomasMcDonald - not for on the fly querying, unless you know that StackApps is id 101 off hand. –  Kevin Montrose Oct 14 '11 at 20:28
Well, I was referring more to knocking the * off the end and using the remainder instead. –  nobody Oct 14 '11 at 20:30
@ThomasMcDonald - ah, sorry I misunderstood. I'll think on that, probably not a bad idea. –  Kevin Montrose Oct 14 '11 at 20:31
@Kevin, at least take off the .com, having dots in the middle of an url doesn't sound that normal? –  Jonathan. Oct 14 '11 at 20:58
@Kevin, isn't it possible to get a certificate that covers more than one domain? –  Jonathan. Oct 14 '11 at 20:59
You only have a handful of unique URLS:,,,,, - Surely you would just get a wildcard SSL cert for then individual certs for those that have top level domains. –  Marco Ceppi Oct 14 '11 at 22:08
@Marco - wildcards certs don't descend beyond one level. * matches but not or It's kind of a crock IMO, but that's the way they work. –  Kevin Montrose Oct 15 '11 at 0:27
@KevinMontrose Good point, I forgot it was api. –  Marco Ceppi Oct 15 '11 at 0:34
@KevinMontrose you could change the api URL to math.api.stackexchange, and So kind of like option 3 & 4 but without the site in the query string or path. –  Jonathan. Oct 15 '11 at 10:05
@Jonathan - eh, once we're changing domain naming schemes I'd rather simplify. It'd also be pretty weird to make api. anything but the lowest subdomain, can't think of anyone who does differently. That'd also still be a lot of certs, *, *, *, and then equivalents for SO, SU, SF, Stack Apps, Ask Ubuntu, and * Schemes 2, 3, & 4 get us down to two, * and * –  Kevin Montrose Oct 15 '11 at 15:34
@KevinMontrose, I see the point about simplifying it. I have read lots about "problems" where there is more than one site on a server, having different certificates for multiple sites on one IP. Surely stack exchange is the opposite of that problem? –  Jonathan. Oct 15 '11 at 15:58
I was disappointed to hear about the limit to wildcard certs. This site proports to sell certs that will work for and - Their copy says: Even more, DigiCert WildCard ssl certificates are unique in allowing you to secure ANY subdomain of your domain, including multiple levels of subdomains with one certificate. For example, your WildCard for * com could include as a subject alternate name. –  Eric Bloch Dec 1 '11 at 0:17

2 Answers 2

I never thought about that — that's a serious problem. I totally understand throwing option #1 and #2 out — they're either impractical or impossible.

I strongly suggest going with option #3. I would really like to avoid seeing another query string parameter — especially one that will be almost guaranteed to be a part of every single request. StackMobile uses option #3 — a sample URL looks like this:

I might also suggest a slight modification to option #3. Can the parameters for the site and the API version be switched around? Then a URL would look like:

Also one question: would the traditional URL paths still be available for non-authenticated requests or would all requests go through

share|improve this answer
There are IIS reasons for wanting to know the maximum path length in advance, which is the technical reason for preferring #4 over #3. It'd be an annoying reconfiguration (and a brief outage of not just the API but each site) to accommodate a new "biggest ever" domain name. While I agree the aesthetics are a toss up, the technical impetus sways me to option #4. I also see no reason to accept unauthenticated requests on the old api.* domains, that would confuse developers I suspect (it would ease transition, just not enough IMO) and would need some extra engineering effort to support. –  Kevin Montrose Oct 15 '11 at 0:34
@Kevin: I see - and I understand the technical implications of lengthening the maximum path length. I guess #4 is the only suitable option then and I will look forward to being able to give it a spin when the beta is ready. –  Nathan Osman Oct 15 '11 at 0:36
P.S. If you have definitely decided on #4, I can begin making some adjustments to my API wrapper(s) in advance. –  Nathan Osman Oct 15 '11 at 0:37

Copying my comment from above in the hope it gets more listen as it's a path for option #1, which if practical for your ops team, seems best.

I was disappointed to hear about the limit to wildcard certs. purports to sell certs that will work for and - Their copy says: Even more, DigiCert WildCard ssl certificates are unique in allowing you to secure ANY subdomain of your domain, including multiple levels of subdomains with one certificate. For example, your WildCard for * com could include as a subject alternate name.

I am not affiliated with digicert in anyway; just surprised by the issue, googled, and well...

share|improve this answer
Unfortunately it's too late - v2.0 of the API has already entered private beta. –  Nathan Osman Dec 11 '11 at 6:03
In brief what they are doing is a hack of a UCS cert with SANs and wildcard certs, this is not something i would rely on to work everywhere especially with any number of libraries that don't have the rich ssl implementation that browsers have. Also at something like 400 FQDNs we would ahve to secure we wouldn't be able to get a cert with enough SAN entries anyway. –  Zypher Dec 11 '11 at 21:27

You must log in to answer this question.

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