Feb 11, 2015 by Pete Holiday Support

Taking a Hard Look at API v2.0

MailChimp's API powers our mobile apps and integrations with other services, and our customers use it to sync their internal data with their mailing lists. We serve 50 million successful API requests each day to a quarter of a million distinct users.

It's big. And in the last 18 months, we made 2 big changes: We introduced API v2.0 in mid-2013, and debuted a new support system in early 2014. We learned a lot from working on these updates, and now we have a better idea of how people use our API and what we can do to make it even more useful.

To begin with, adoption of API v2.0 was pretty slow. After a year and a half, requests to v2.0 only amount to a third of our API traffic and many of those requests come from our own mobile apps or users who joined after it was released. Our users and integrations simply haven't found a compelling reason to upgrade from v1.3 to v2.0.

But redefining API support was a big win for our users. Before, our engineers would try to answer questions in a Google Group. Now, our awesome customer support team handles all that. With a better system in place, support requests started increasing. More tickets meant more issues being discovered, reported, and fixed.

Next, we worked with MailChimp's UX Research team to survey API users. This included users who were coding for themselves as well as developers who were writing code to integrate MailChimp with other services. The results were mixed. An overwhelming majority of those surveyed were happy with the API. But the survey also provided a lot of insight into the low adoption rate and the ticket volumes we were seeing.

We also found that developers working with v2.0 were running into problems. That version has nearly 120 distinct endpoints—that's a lot of complexity! The documentation was incomplete and, in some cases, flat out wrong. There were oddities that had been in the API for so long that we couldn't really fix them without breaking backward-compatibility. The API was also starting to lag behind on features; we found building new endpoints to be more complicated than it should be.

Here's one example of this complexity. We wanted to make sure that our documentation matched the actual behavior of the API. Since there are plenty of tools to turn comment blocks on functions and class methods into human-readable documentation, we decided to use reflection to parse those comments and use that information to type-check incoming requests. Unfortunately, this caused as many problems as it solved.

It wasn't obvious to our engineers that this was necessary during development. An engineer might assume that the type-checking system was working for our responses as well, but that wasn't the case. Worst of all, it essentially turned those comments into executable code. A typo in a comment could easily break the API.

If you ever find yourself saying, "We really need some unit tests around those comments," well, you probably made a wrong turn somewhere.

After thinking on it, we decided that all of these things were symptoms of a larger problem: we hadn't been treating our API like a first-class feature of our application. We weren't giving it the attention it deserved, and it showed.

Now, we've changed our attitude, and we're actively working to fix problems at a structural level. In the coming weeks, we'll delve further into how we plan to do that. We're excited about where the API is headed, and hope you are too. Stay tuned.