Notice of Upcoming Endpoint URL changes

[jesse]

*** Before anyone freaks out: if you are using the API with an account
today, you WILL NOT be affected. That would just be mean. ***

I. OVERVIEW
Over the next few weeks, we'll be turning up a new, geographically
disparate datacenter. This is not a redundant datacenter, though, so
this may impact some folks in the semi-near future. The most impacted
groups will be developers with new clients, plugin developers, and
integrators.

*** In case you missed it: if you are using the API with an account
today, you WILL NOT be affected. That would just be mean. ***

II. IMPACT
So, what's the impact you wonder? If you've been using the API, you'll
know that the endpoint for all connections currently are at
http://api.mailchimp.com/

Additionally, if you've been using the web app, you may have noticed
that URLs have started to change from
http://admin.mailchimp.com/
to:
http://us1.admin.mailchimp.com/

over the past few months. Basically, the API is about to get the same
treatment. The reason existing users will *not* be affecteced is that
we are going to continue to point *both* api.mailchimp.com and
us1.api.mailchimp.com at the exact same datacenter, "us1". When we
turn on the new datacenter, "us2", a majority of new accounts will end
up there and will need to access a new URL for their API endpoint:
http://us2.api.mailchimp.com/

Sounds like a pain going forward, right? Well, we're definitely trying
to ease the pain through the following changes:

1) API Keys will start to *always* be presented with the proper
datacenter encoded in them. So the key "XXXXX" will now be "XXXXX-
us1", however YOUR EXISTING KEY DOES NOT ACTUALLY CHANGE. The point of
doing that is to allow API wrappers to point themselves at the proper
datacenter without needing to know anything but the API Key.

2) We have already updated our API wrappers to submit to the proper
datacenter - these can be used as dropin replacements in your
projects.

3) We are writing up and distributing information (you are reading it)
about the change and contacting developers so they can be proactive in
making changes.

4) Further warning against using the login() method for anything by
deprecating it in the API docs. It will be removed in subsequent API
releases

5) To support existing users, building in defaults everywhere such
that if a datacenter hint does not exist in an API key, we'll assume
you are in "us1".

6) We will be examining plugins and wrappers and marking them with
warnings for new users until they are updated.

III. CHANGES REQUIRED GOING FORWARD
* Existing individual users with working solutions: nothing, you can
essentially ignore this... until you setup a new account a try to use
the same code.
* New accounts: be sure to get a datacenter-supported version of the
api wrapper or hard code your host in custom solutions
* Plugin/Wrapper developers, & Integrators: don't use the login()
method and start peeling off the datacenter and submitting to the
datacenter specific endpoints

IV. FAQ
1) Does this mean my API stuff is going to break?!?!
For existing accounts, no. If you have clients or have integrated with
us, future users may have problems.

2) Why a new datacenter?
We've experienced enormous growth over the past year and are close to
outgrowing the available space in our current datacenter. That meant
that we either stop growing (yeah right), have like a week long
downtime to move a ridiculous amount of data (um, no), or structuring
our platform so it can run in several datacenters at once. Since we
plan on staying in business, we chose the latter. An awesome benefit
of this is that we are also considering supporting *international*
datacenters which would improve app performace and latency. Be patient
with that one.

3) Why not just redirect like the web app does when I login?
There are several reasons for this:
a) Lots of API wrappers are not built to support 301 or 302
redirects. Sounds lame, but it's very standard
b) Very few, if any, libraries properly support redirecting a POST
request (they'll redirect, but using a GET and dropping POST
variables)
c) Load and latency: that basically would mean we'd have one huge,
honking proxy running - which ever data center it would in would have
ok performance, but no others would

4) I'm not sure I understand the fix for my wrapper or custom code,
can you give me a code example?
Sure... here's some PHP:
$api_host = 'api.mailchimp.com';
$api_key = 'XXXXX-us2';
list($key, $dc) = explode('-',$api_key,2);
if (!$dc) $dc = 'us1';
$api_host = $dc.'.'.$api_host;

5) Can I get that code in my language?
No, it's really not that hard to port to whatever language you are
using.

6) Are you going to update version 1.0 or 1.1 wrappers and other code?
v1.0 - no. v1.1 - yes.