API Endpoint Changes Coming In Version 2.0

Question

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.

Answer 1

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?

Answer 2

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...