Supporting Mixed Mode Services in an API

A new contact management system

In 2013, Constant Contact started to roll out our next generation of contact management features.  This new generation of CRM was not just some additional functionality – we moved to a new hardware architecture, a new software technology stack and a modern UI design to improve usability.  All in all, it was a total migration from old to new.  This is the story of how we implemented these changes in the Constant Contact API, and the decisions we made along the way.

The impact to our API platform

The change would be critical to Constant Contact. It would allow us much more flexibility in determining what a contact is, better sorting, searching and management. Additionally, it would afford us an extensible platform to build all of our next generation products from.

As we started to develop our API endpoints for our new platform, we realized there were a few things we needed to tackle before releasing anything to our developers.  Of course, we needed to handle the migration of data.  But the new platform was also fundamentally different; many assumptions and behaviors that were normal in the older platform were no longer appropriate.

As the API platform team, we were very concerned with how to provide a consistent, predictable platform to our 1000s of developers who don’t know anything about the massive changes we were undertaking.

Rules on how to proceed

As we examined and planned, we made a few rules on how to proceed:

1. Assume developers don’t know we have two CRM platform versions (and don’t want to know!)
2. Assume integrations will be working with both our old and new CRM platforms at the same time (and shouldn’t know it!)
3. Assume that developers of integrations won’t want to redevelop their integrations unless there is a really good reason (and because we’re migrating our internal platform is not a good reason!)

With those rules in place, it became clear to the team that we had a lot of work to do.

First, there were some fundamentally game changing behaviors we had to account for.  A quick example:  in our old platform a contact could only have a single email address. But in our new platform, a contact could have up to 10 email addresses.  Conversely, a contact in our old CRM had to have an email address whereas a contact in our new platform didn’t need an email address.  Talk about new extremes and rules to play by!

So, what is an external API team to do to make sure their customers don’t have any disruption in service and won’t have to make any changes for the new system?

Also, how do you hide the fact that the two platforms are fundamentally different and offer different functionality?

We decided to use one of our team’s favorite mantras: Keep It Simple Stupid.  We maintained with the baseline functionality of our old contact platform until 100% of our customers were migrated.  Once 100% migrated, we would add in the new functionality over time in a way that would be backwards compatible and not break existing integrations.

By making these two decisions early, we had a very simple rule to follow as we went forward:

Make everything work for both platforms the same way as it did in the old one, but design to support the new platform without architecture changes.

This helped us make some hard decisions early and stay on the right track.  We definitely had some learning experiences along the way.  Since we’ve been operating in a mixed mode world for nearly 8 months now, here are some of our team’s takeaways:

• Automated tests are twice as hard – you have to maintain them for both platforms for all your API endpoints.
• Automated tests are also twice as important – when you have two platforms that can change and be out of sync, you have twice as many potential failures.
• Domain knowledge for a new platform doesn’t exist on your API team – you have to partner with your platform teams internally to get the domain expertise early and often.  Embedding someone from your internal services team on your API team is a simple way to get large gains.
• If both teams are agile and moving fast, communication has to move even faster.  A large portion of our defects and production issues were caused purely by not knowing something had changed on the contacts platform until it was in production.
• Communication is not just for internal teams!  Your developer ecosystem will be much more cooperative, understanding and helpful if they know that you’re doing a mixed mode and migration.
• There is no way you can account for everything.  You can plan all you want.  You can stress all you want.  You will miss something.  But you’re dealing with developers who have released buggy software, they will forgive you if you respond and react quickly.
• And that brings us to our last learning: the most important part of working in mixed mode on such a complicated product is to be able to listen early and often and respond quickly and effectively.

The past year has been quite an adventure for the team.  We’ve learned so much, had so many great interactions with our developer ecosystem and accomplished quite a task during this migration.

Have you ever had to support mixed mode services or products in an API?  Share your learnings or questions below!