Wix: Linear Migration Makes API Updates Less ‘Hellish’
Cloud-based website builder Wix recently rewrote its checkout API making the transition with zero incidents. How the company engineers carried out the task — using a technique called linear migration — might point to a better way to do application migrations.
There are countless articles about migrations — it’s a topic covered ad nauseam. But the blog post by Wix Front End Developer Ariel Livshits stood out because of what wasn’t discussed. The post wasn’t about how the code was updated; it covered the way the migration was performed. Wix rewrote its checkout API and had to migrate it in a way with no downtime and as little incidents as possible.
Rather than going through a cycle migration, company engineers did a linear migration, which provided a seamless user experience with no incidents.
Seamless Shopping
A seamless shopping experience for the user is an incredibly complicated task for developers.
The work was done for Wix Stores, which is responsible for all eCommerce-related services on a Wix site. This encompasses all things shopping, covering inventory, widgets (product gallery, widgets), the checkout process, and anything else in between.
Livshits provided an example of a site for yoga classes that may use the service. When a student books a class, Wix handles the payment. When payment is sent, a confirmation email follows. Voila, simple booking service.
But say the yoga class expanding into yoga mat sales. What was once a simple booking service now needs to handle two different types of transactions — bookings and product sales. The need for a single checkout service that supports different needs is now introduced. Livshits explains that this is where he came in.
His task: replace the current API with a new API — one checkout service that supports all the different entities. Migrate the entire API usage in their client’s projects. Wix stores would be the first big user of the new API.
Meet the Checkout Service
Before moving forward with a migration, here are details about the legacy checkout API usage:
- Everything is controlled in client-side services.
- Wix doesn’t have a mapper layer for API data from the server. A mapper layer is a layer that handles transferring data from a persistent data store in-memory representation and isolating them from each other. In the case of Wix, it’s the data transferred from server to client.
- The checkout object is huge and complex.
The goal with the new API was to have no side effects that will change and affect the data consumed in the checkout client.
The OG Migration Cycle
Livshits explains that he usually sees migrations happen in a cycle with the starting point being the new feature toggle with the following steps coming afterward:
- Split the code between the new and old API.
- Test all new scenarios.
- Pass the QA checks.
- Open to users.
If something goes wrong the whole cycle starts again.
Of this, he is not a fan.
Introducing Linear Migration
This is how Livshits avoided the “hellish cycle” listed above and made the migration “faster, safer, and simpler”.
There are four phases in linear migration.
- Legacy phase (current production phase).
- Compare and return legacy.
- Compare and return new.
- New (feature toggle is now open in production).
A Frontend Server (FES) will serve as a bridge from the old API to the new API. The client checkout will call the FES which will be in charge of calling the new API. This will help avoid a huge client code change (it could get up to an entire project rewrite).
To avoid any client-side change, the FES will hold a layer of mappers and the new object will return as the legacy object. Each phase will be responsible for deciding whether to call the legacy or new API.
The data is another key factor in achieving a linear migration. The FES makes it possible to return the new and legacy objects in the same structure meaning real data comparison is also possible.
Livshits says, “The secret ingredient of linear migration is real data comparison.”
Real Data Comparison — The Compare Phase
Both objects are sent for comparison before one is returned to the client. In both compare phases, we call both APIs but will only return one result as a response. Both results are sent to a comparable engine.
The comparable engine will assess what’s missing or what needs to be fixed in the new API. The goal is 100% equality between both objects before the new API is released to users.
In some cases, there will be differences between the API’s payloads that can be solved with a few simple approaches. For example, if the new API as a field that the old API doesn’t have, that can either be ignored or defaults can be added.
Because this is a safer migration, production data is used without production users being harmed.
The compare phase moves “Pass the QA” and “Open to Users” phases back into the development cycle and removes any chance of incidents.
When developers get to 100% parity, far above the level of certainty seen before, the feature toggle is opened and the users are introduced to the new API.
Conclusion
Linear migration is based on data. Wix’s goals during this migration were to refactor as little as possible, migrate as fast as possible, and keep production safe. Linear migration made that possible.
Millions of users were supported during this migration.
