A few weeks ago, I wrote about some of the issues we discovered when we took a hard look at our API v2.0. Today, I'll show you how we're fixing them.
Many of the problems people encountered with older versions of the API were systemic or architectural. But since we can't make backwards-incompatible changes, the only way to make things better is to release a new version. So that's what we did. MailChimp API v3.0 is now in public beta, and I'm here to tell you all about the improvements it'll bring.
The most frustrating thing about v2.0 was its inconsistency. That was never more obvious than when the documentation described one thing, but the API did something else entirely. Oof. While the existing documentation inconsistencies could have been fixed without creating a new version of the API, we saw the errors as a symptom of a larger problem. It was too easy to modify an end-point without updating the documentation, and too easy to create a new end-point that was inconsistent with other end-points within the API. The architecture of v2.0 and its predecessors was too flexible and open-ended. It didn't lead developers down the right path. And when your system makes it easy to go down the wrong path, you shouldn't be surprised when that's where your developers end up.
We fixed that in v3.0 by baking in the consistency. We used JSON Schema to describe the input and output of every endpoint. More importantly, the API itself now makes use of those schema files to validate user input and generate the responses, making it very difficult to produce inconsistent output. Those schema files are also a key piece of both our documentation and our new libraries.
All of those problems could have been solved behind the scenes, at least in theory. In practice, it would have been incredibly difficult to maintain perfect backwards compatibility (including replicating our long-standing bugs) while also changing the core architecture. That's especially true because we didn't have a source that we trusted to describe the API perfectly.
Fixing v2.0's architecture issues in-place wouldn't have allowed us to address the other major issue: its complexity. API v2.0 had more than 100 different methods, all of which took their own inputs and produced their own outputs. Those end-points weren't particularly intuitive. It was nearly impossible to develop for the MailChimp API without constantly referring back to its documentation, even if you were using one of our official libraries. There was no good way to hide that complexity.
But our switch to a RESTful API helps tame that complexity. API v2.0 consisted of an eclectic mixture of nouns and verbs. In v3.0, we've replaced them with resources (nouns), and you indicate what you want to do to them with standard HTTP methods (GET, POST, PATCH, and DELETE). Once you learn what resources are available, it's easy to predict what calls you'll need without having to page through the documentation. Simpler, and less time-consuming.
The new version also enables a more robust feature set. By launch, you'll be able to work with automation, create lists, upload files to the file manager, and work with drag and drop campaigns and templates. And that's just the tip of the APIceberg. We have a number of exciting new features we're not quite ready to share with the world yet, but stay tuned.
Getting started with v3.0
In the meantime, we'd love for you to dig in. While we put the finishing touches on our official documentation, we have some temporary resources to help you find your way around in our examples repository. The only thing we ask is that you hold off on pushing your new code to production, because we can't guarantee that any of the end-points will remain in their current state between now and our official launch. But that also means that we're eager to hear your feedback. Email firstname.lastname@example.org with your questions or comments. We can't wait to see what you build!