17

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 api.stackexchange.com using a header to select the site
  3. likewise, but embed the site in the path as in api.stackexchange.com/stackoverflow.com/2.0/questions
  4. again, but use a query string as in api.stackexchange.com/2.0/questions?host=stackoverflow.com

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 api.stackexchange.com.

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.

13
  • Would it not be better to use a unique ID for each site, rather than the domain? apple, gaming, wordpress etc?
    – nobody
    Oct 14, 2011 at 20:25
  • @ThomasMcDonald - not for on the fly querying, unless you know that StackApps is id 101 off hand. Oct 14, 2011 at 20:28
  • Well, I was referring more to knocking the *.stackexchange.com off the end and using the remainder instead.
    – nobody
    Oct 14, 2011 at 20:30
  • @ThomasMcDonald - ah, sorry I misunderstood. I'll think on that, probably not a bad idea. Oct 14, 2011 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, 2011 at 20:58
  • 1
    @Kevin, isn't it possible to get a certificate that covers more than one domain?
    – Jonathan.
    Oct 14, 2011 at 20:59
  • 1
    You only have a handful of unique URLS: stackoverflow.com, stackexchange.com, superuser.com, serverfault.com, stackauth.com, askubuntu.com - Surely you would just get a wildcard SSL cert for stackexchange.com then individual certs for those that have top level domains. Oct 14, 2011 at 22:08
  • 3
    @Marco - wildcards certs don't descend beyond one level. *.stackexchange.com matches math.stackexchange.com but not api.math.stackexchange.com or api.meta.math.stackexchange.com. It's kind of a crock IMO, but that's the way they work. Oct 15, 2011 at 0:27
  • @KevinMontrose Good point, I forgot it was api. Oct 15, 2011 at 0:34
  • @KevinMontrose you could change the api URL to math.api.stackexchange, and math.meta.api.stackexchange.com. So kind of like option 3 & 4 but without the site in the query string or path.
    – Jonathan.
    Oct 15, 2011 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, *.stackexchange.com, *.api.stackexchange.com, *.meta.api.stackexchange.com, and then equivalents for SO, SU, SF, Stack Apps, Ask Ubuntu, and *.stackauth.com. Schemes 2, 3, & 4 get us down to two, *.stackexchange.com and *.stackauth.com. Oct 15, 2011 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, 2011 at 15:58
  • I was disappointed to hear about the limit to wildcard certs. This site digicert.com/welcome/wildcard-plus.htm proports to sell certs that will work for foo.bar.example.com and bar.example.com - 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 *.digicert.com com could include server1.sub.mail.digicert.com as a subject alternate name.
    – Eric Bloch
    Dec 1, 2011 at 0:17

2 Answers 2

4

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:

http://stackmobile.com/stackoverflow.com/questions/

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:

http://api.stackexchange.com/2.0/superuser.com/questions

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

3
  • 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. Oct 15, 2011 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. Oct 15, 2011 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. Oct 15, 2011 at 0:37
0

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. digicert.com/welcome/wildcard-plus.htm purports to sell certs that will work for foo.bar.example.com and bar.example.com - 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 *.digicert.com com could include server1.sub.mail.digicert.com as a subject alternate name.

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

2
  • Unfortunately it's too late - v2.0 of the API has already entered private beta. Dec 11, 2011 at 6:03
  • 2
    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, 2011 at 21:27

You must log in to answer this question.

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