Learn GraphQL - Migrating from REST to GraphQL

#Introduction

Most teams adopting GraphQL don't start from zero — they have a working REST system. Episode 47 discusses migrating from REST to GraphQL with a safe, gradual strategy that doesn't stop the service.

We'll plan the migration, apply the strangler fig pattern, build a GraphQL wrapper for REST, migrate clients, and evaluate the results afterwards.

#Planning Migration

#Assessment and Inventory

Migration starts with mapping, not code. Build a complete inventory:

• A list of REST endpoints and their functions.
• Client consumption patterns (web, mobile, third-party).
• The data every screen/use case needs.

/users           -> query user(id)
/users/:id/posts -> query user(id) { posts }
/posts           -> query posts(first, after)
POST /posts      -> mutation createPost

From here set priorities: choose the use cases that benefit most from GraphQL (high over-fetching, N+1 requests) to migrate first, as proof of success (quick wins).

#Timeline, Risks, and Success Criteria

Set a realistic timeline (weekly, not "all at once"), identify risks (unchangeable clients, neglected legacy services), and define measurable success criteria: latency drops by a certain percent, fewer requests per view, and no functional regressions.

#Incremental Migration

#Strangler Fig Pattern

The strangler fig pattern shifts the legacy system bit by bit: the new system "wraps around" the old one until it eventually replaces it. For GraphQL:

1. Build the GraphQL server alongside REST.
2. Migrate one use case (query/endpoint) at a time.
3. New clients use GraphQL; old ones keep running on REST.
4. After everything moves, shut down the unused REST endpoints.

#Running REST and GraphQL in Parallel

Run both simultaneously — this removes the "all or nothing" pressure. Use feature flags to route some clients to GraphQL, then expand the scope gradually. Every small release can be rolled back without stopping the service.

#GraphQL Wrapper for REST

#RESTDataSource Pattern

When a REST API can't be changed, wrap it with GraphQL. RESTDataSource (episode 8) is the main bridge:

REST wrapper in GraphQL

import { RESTDataSource } from "@apollo/datasource-rest";
 
export class UsersAPI extends RESTDataSource {
  baseURL = "https://legacy-api.example.com/";
 
  async getUser(id) {
    return this.get(`/users/${id}`);
  }
 
  async getPosts(userId) {
    return this.get(`/users/${userId}/posts`);
  }
}

#Mapping and Error Handling

First inspect the REST response shape, for example with curl https://legacy-api.example.com/users/1. Map REST responses to GraphQL shapes in the data source or resolver, and translate REST errors into GraphQL errors (episode 11). Also pay attention to caching: legacy REST APIs may already have cache headers — leverage them in the data source.

#Client Migration

#Apollo Client and Backward Compatibility

Client migration happens gradually:

1. Add Apollo Client alongside the old HTTP client.
2. Replace one screen at a time.
3. Maintain backward compatibility: old features keep working via REST until done.

A/B testing GraphQL vs REST

const useGraphQL = featureFlags.get("graphql-profile");
 
if (useGraphQL) {
  return useGetUserQuery({ variables: { id } });
}
return useLegacyRestUser(id);

#Rollback Strategy

Prepare rollback at two levels: a feature flag to turn off GraphQL at any time, and a deployable version you can return to. Communicate the migration schedule to internal users — API changes rarely cause technical problems; they often cause communication problems.

#Post-Migration

#Deprecation and Monitoring

After clients move:

• Deprecate REST endpoints: mark them deprecated, monitor their traffic, then turn off the unused ones.
• Monitor both systems: compare error rates and latency of the old REST versus the new GraphQL during the transition.

#Evaluation and Documentation

Compare against the success criteria: measure round-trip reductions, latency, and development ease. Write down lessons learned (episode 49) and update the documentation — the new GraphQL schema is now the team's main contract.

#Conclusion

Key takeaways:

• Start from an endpoint inventory and use-case priorities, not code.
• The strangler fig migrates legacy systems gradually.
• Run REST and GraphQL in parallel with feature flags for safe rollback.
• RESTDataSource wraps REST APIs that can't be changed.
• Migrate clients screen by screen with backward compatibility.
• Evaluate against success criteria and document the lessons.

In the next episode, episode 48, you'll learn about GraphQL in various languages — Graphene and Strawberry for Python, GraphQL Java and Spring Boot, gqlgen for Go, GraphQL Ruby for Rails, Lighthouse for Laravel, Hot Chocolate for .NET, and Juniper for Rust. GraphQL isn't just for JavaScript!