---
title: "Strangler Fig pattern for API versioning"
description: "Learn how the Strangler Fig pattern enables seamless API versioning by gradually replacing legacy systems without downtime."
canonicalUrl: "https://zuplo.com/learning-center/strangler-fig-pattern-for-api-versioning"
pageType: "learning-center"
authors: "josh"
tags: "API Versioning"
image: "https://zuplo.com/og?text=Strangler%20Fig%20pattern%20for%20API%20versioning"
---
The **Strangler Fig pattern** is a method for modernizing legacy APIs without
disrupting users or causing downtime. Inspired by how a strangler fig plant
replaces its host tree, this approach allows old and new systems to coexist,
with functionality gradually transitioning to the new system.
### Key Points
- **What It Is**: A step-by-step approach to replace old APIs by introducing a
new system alongside the existing one, using a facade to manage traffic.
- **Why Use It**: Reduces risk compared to a full rewrite, avoids downtime, and
allows incremental updates.
- **How It Works**:
- Introduce a facade to route requests between old and new APIs.
- Migrate functionality in small, manageable pieces.
- Test and validate each change before retiring legacy components.
- **Tools**: Platforms like Zuplo assist with routing, monitoring, and managing
API migrations efficiently.
This method is particularly useful for transitioning to microservices or
updating API versions while maintaining stability and user satisfaction.
## Video: Strangler Fig Pattern | Migrate Monolithic Application to Microservices Architecture
Strangler fig is not a pattern that is limited to API versioning. Check out this
video which explains the pattern in the context of microservice migrations to
get the full picture:
## How the Strangler Fig Pattern Works for API Versioning
The Strangler Fig pattern allows legacy and new API versions to operate side by
side, enabling a smooth and controlled transition without disrupting users.
At its core, this pattern introduces an intermediary layer that sits between API
consumers and backend systems. This layer handles routing, ensuring requests are
directed to the appropriate API version based on specific rules. Let’s break
down how this routing system works during migration.
### Using a Facade for Request Routing
The facade acts as the central routing layer, intercepting all incoming requests
and directing them to the correct API version based on predefined rules.
Initially, most requests are routed to the legacy API. As new features are
rolled out, the facade gradually shifts targeted requests to the updated
components. This ensures API consumers experience no interruptions or
compatibility issues during the transition.
The facade’s routing decisions can be based on various factors such as headers,
URL paths, client IDs, geographic data, or specific payload characteristics.
This flexibility allows teams to roll out new features to select user groups,
test performance, and address any issues before a full-scale deployment. If
problems arise, the facade can instantly redirect traffic back to the stable
legacy version.
### Step-by-Step Migration Process
Migrating with the Strangler Fig pattern involves a structured process that
minimizes risks while allowing teams to learn and adapt. Each step builds on the
last, creating a clear path from old systems to modernized architecture.
The process starts with clearly identifying system boundaries and dividing the
API into smaller, manageable components, often referred to as "thin slices".
Once these slices are defined, an intermediary layer is introduced to allow
seamless integration of new components without disrupting the existing system.
A great example of this is
[AltexSoft](https://www.altexsoft.com/software-product-development/)’s migration
of a 20-year-old property management system. The team updated the database
structure, added new tables, and deployed new features while ensuring the legacy
system remained functional. As new components were tested and validated, they
were gradually integrated into the modern architecture.
The migration typically follows a cycle: develop a new component, route traffic
to it, monitor its performance, and retire the corresponding legacy component
once it’s proven reliable. Over time, the facade evolves, starting with basic
passthrough routing and gradually handling more complex traffic patterns as the
migration progresses.
The end goal is to fully decommission the legacy system once all functionalities
have been successfully transitioned. At this point, teams can either remove the
facade entirely or keep it as an adapter layer for legacy clients who haven’t
updated their integration methods.
## Step-by-Step Guide to Implementing the Strangler Fig Pattern
Implementing the Strangler Fig pattern requires thoughtful planning and a
structured approach. This method ensures a seamless shift from legacy APIs to
modern alternatives.
### Assessing the Legacy API
Start by thoroughly analyzing your API's architecture, dependencies, and key
functionalities. Map out all endpoints, data flows, and integration points to
create a detailed migration plan. Collaborate with experts to uncover hidden
business logic and edge cases that might complicate the process. To better
understand the current system, develop automated black-box and performance tests
that capture its behavior. Adding strategic logging in critical areas - using
techniques like aspect-oriented programming - can also provide valuable insights
into how the API performs in production.
Break the system into smaller, manageable "thin slices" and prioritize
components based on business needs. Begin with a low-risk section of the system
to gain confidence before tackling more critical features. Once you’ve mapped
out the legacy API, move on to setting up a gateway to manage traffic
effectively.
### Setting Up a Facade for Traffic Interception
Deploy an API gateway to serve as the central hub for routing requests.
Configure it to direct traffic based on HTTP headers or URL paths. For instance,
if you're updating an e-commerce checkout API from version 1 to version 2, you
could route requests with a specific header (e.g., `x-version=v2`) to the new
version, while all other requests default to the legacy API. This approach
avoids the need for additional proxy layers or overly complex URL structures.
Use access logs to verify that routing behaves as expected and to troubleshoot
any issues that arise.
### Gradual Migration and Testing
Migrate incrementally, testing at every stage to ensure backward compatibility.
For example, provide default values for new endpoint parameters so existing
clients remain unaffected. Use unit, integration, and regression tests to catch
potential issues early in the process. This steady and deliberate approach
allows for a smoother transition. Keep an eye on API adoption rates to determine
which versions are actively used, and communicate updates clearly through
release notes, migration guides, and updated documentation.
Once the new API versions are stable and meet performance expectations, you can
begin deprecating the legacy endpoints.
### Removing Legacy APIs
When the migration is complete and stable, start phasing out legacy APIs.
Provide a clear timeline for deprecation and continue supporting older versions
during the transition period. Before retiring any legacy endpoints, confirm that
they are no longer handling significant traffic. Offer detailed documentation
and support to ensure users feel confident throughout the process. For example,
a major grocery retailer modernized its coupon management system by first
targeting the frequently used but less complex `/get_coupons` endpoint. This
allowed them to validate their approach before moving on to more challenging
components.
## Tools and Platforms to Support Migration
Migrating systems using the Strangler Fig pattern requires tools that can handle
intricate routing and monitoring tasks. These tools ensure a smooth transition
while minimizing disruptions to users.
### Zuplo for Programmable API Management
Zuplo stands out from traditional API gateways by offering programmable
capabilities that allow custom code for advanced routing. Its integration with
[GitOps](https://www.redhat.com/en/topics/devops/what-is-gitops) ensures that
every change - whether it's routing, policy updates, or configuration tweaks -
is version-controlled and auditable. This approach minimizes the risk of losing
progress or unintentionally rolling back critical rules.
Zuplo is OpenAPI-native, which keeps your gateway aligned with your API
specifications throughout the migration. This means as you develop new API
versions, the gateway configuration stays consistent with the documented specs,
eliminating mismatches between what's deployed and what's described.
The **developer portal** is another key feature, providing separate, interactive
documentation for both legacy and new API versions. This makes it easier for API
consumers to identify the correct endpoints during the transition.
Zuplo also offers **extensive customization**, allowing you to create routing
logic tailored to user segments, geographic locations, or specific usage
patterns. This flexibility is crucial for managing the complexities of legacy
systems.
> "Zuplo lets us focus on our API's value, not the infrastructure. Native GitOps
> and local development works seamlessly. Customizable modules and theming give
> us complete flexibility. Easy recommendation." - Matt Hodgson, CTO, Vendr
Additionally, Zuplo’s **edge deployment** processes routing decisions closer to
users, reducing latency - a critical factor when balancing traffic between
systems with different response times or geographic distributions.
Now, let’s explore how Zuplo supports monitoring and analytics during migration.
### Monitoring and Analytics with Zuplo
Zuplo pairs its routing capabilities with robust monitoring tools to help you
maintain stability throughout the migration. Its analytics provide real-time
insights into both legacy and new API versions, allowing you to compare
performance, track error rates, and observe usage trends.
**Custom policies** enable advanced migration strategies, such as deploying
canary releases to test new versions with specific user groups or automatically
rolling back traffic if error rates spike. This ensures a controlled and
reliable transition.
The analytics dashboard offers a clear view of traffic distribution across API
versions, making it easier to phase out legacy endpoints. By tracking adoption
rates of new versions, you can identify and address potential issues before they
escalate.
Security and performance are maintained through **rate limiting and
authentication policies**. For example, you can apply stricter rate limits to
legacy endpoints while ensuring new versions can handle the expected traffic
load.
## Benefits and Challenges of the Strangler Fig Pattern
Building on the migration steps mentioned earlier, let's dive into the key
advantages and operational hurdles of using the Strangler Fig pattern.
This pattern offers a practical way to manage
[API versioning](https://zuplo.com/blog/2022/05/17/how-to-version-an-api) while
minimizing risks. One of its standout benefits is **risk reduction**, as it
allows for controlled testing and validation of each change. Additionally, it
provides **immediate value** to users by enabling incremental updates rather
than forcing a complete overhaul in one go.
Another major plus is **zero downtime**. Users can continue accessing familiar
endpoints without interruptions, avoiding the confusion and frustration that
often come with abrupt system changes.
However, the pattern isn't without its challenges. Running old and new systems
in parallel **increases resource demands** and adds complexity to operations.
Essentially, you're maintaining two infrastructures during the transition, which
can strain both budgets and team capacity.
### Comparison Table: Benefits and Challenges
| Benefits | Challenges |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Enables a smooth migration from a service to one or more replacement services | Unsuitable for small systems with low complexity |
| Keeps legacy services operational while updating to newer versions | Cannot be applied in systems where backend requests can't be intercepted and routed |
| Allows adding new features and services while refactoring older ones | The proxy or facade layer risks becoming a single point of failure or a bottleneck if poorly designed |
| Useful for API versioning | Requires a robust rollback plan to revert changes safely if issues arise |
| Supports legacy interactions for systems that won't or can't be upgraded | |
While these trade-offs are clear, addressing the operational challenges is
crucial to ensure a smooth migration process.
### Tackling Common Challenges
The **facade layer** is often the most vulnerable point. If it fails, both the
old and new systems could become inaccessible. To mitigate this risk, design the
facade with redundancy and load balancing to maintain availability and
reliability.
**Data consistency** is another critical issue. When both old and new APIs
interact with shared data, synchronization problems can occur. Using
event-driven architectures or shared state management strategies can help
prevent conflicts and keep systems aligned.
Managing **resource usage** and operational overhead requires careful planning.
As traffic shifts from legacy systems to new ones, you can gradually scale down
the resources allocated to older components, keeping costs in check.
Ivan Mosiev highlights another challenge:
> "Ongoing analysis is required to assess the impact on legacy systems, which
> adds complexity as you're dealing with both systems in parallel until the
> migration is finished".
This parallel operation demands constant monitoring and clear communication
across teams to avoid missteps.
Having a **rollback strategy** for each component is non-negotiable. Feature
toggles or dynamic routing make it easier to redirect traffic back to the old
system if something goes wrong. This safety net is especially important during
high-traffic periods when errors can have a greater impact.
The Strangler Fig pattern is best suited for large, complex systems where its
advantages outweigh the added operational demands. For smaller, simpler APIs,
alternative versioning methods might be more cost-effective and easier to
manage.
## Conclusion: API Versioning with the Strangler Fig Pattern
The Strangler Fig pattern offers a practical way to handle API versioning by
gradually phasing out outdated functionalities without disrupting existing
operations. As Martin Fowler puts it:
> "Rather than replacing a system all at once, it's easier to build a new system
> around the old, gradually replacing functionalities until the legacy system is
> phased out."
This method relies on a facade to direct requests between the old and new
services, ensuring everything continues to function smoothly during the
transition.
To make this process more efficient, having the right tools is critical. For
instance, Zuplo supports this approach by enabling
[separate OpenAPI files](https://zuplo.com/docs/articles/versioning-on-zuplo)
for each version, programmable routing through custom policies, and GitOps
workflows with unlimited preview environments. These features ensure precise
version control and allow for easy rollbacks when needed.
For APIs with complex structures, this pattern aligns with key migration
principles. The process hinges on careful planning, ensuring seamless request
interception, reliable data synchronization, and ongoing monitoring.
Whether you're moving from monolithic architectures to microservices or updating
API contracts, the Strangler Fig pattern allows for steady progress while
keeping users happy and systems stable. It provides a structured approach to API
modernization that minimizes risk and maximizes efficiency.