Notice of Upcoming Endpoint URL changes | jesse | 8/20/09 9:27 AM | *** 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. |