Migrating Rest To Graphql

The Legacy Trap: Why Copy-Pasting Resolvers Breaks Production

We built this skill because watching engineers try to wrap a REST API in GraphQL without a strategy is painful. You start with the easy endpoints. You write a resolver that calls fetch or axios. It works in dev. Then you hit production. The N+1 query problem explodes. Your P99 latency jumps from 50ms to 800ms. Your database CPU hits 100%. You try to fix it by adding caching, but now you have stale data. You try to fix that by adding invalidation, and now you have a distributed cache race condition.

The root cause is almost always the same: treating GraphQL as a thin proxy instead of a query language with a strict contract. When you migrate REST to GraphQL, you aren't just adding a syntax layer. You are introducing a new data-fetching paradigm that demands batching, caching, and schema stability. If you skip the structural planning, you end up with a GraphQL API that is slower and more fragile than the REST API it replaced. ^[1]

We see teams burn weeks writing ad-hoc adapters that break backward compatibility the moment a frontend team adds a new field. They forget about DataLoader until the load test fails. They ignore Federation v2 directives until their subgraphs can't resolve entities. This skill exists so you don't have to debug these edge cases in production. If you haven't already, we recommend reviewing building-graphql-server to ensure your base server architecture is solid before you attempt a migration.

The Hidden Tax of a Half-Baked Migration

Ignoring a structured migration strategy costs real money. Every N+1 query is a direct hit to your infrastructure bill. A single endpoint that triggers 100 database queries per request can cost thousands of dollars monthly in compute and IOPS. Beyond the bill, there's the developer tax. Engineers spend hours debugging why a resolver returns null instead of an error, or why the schema drift breaks a mobile app that expects a specific type shape.

Backward compatibility is the silent killer. When you expose a GraphQL API, every field is a public contract. If you rename a field or change a type without a deprecation strategy, you break clients. ^[1] The cost of fixing a broken client in production is ten times the cost of preventing it with proper schema validation. We've seen teams lose customer trust because their GraphQL API returned inconsistent error formats, violating RFC 9457 standards and making it impossible for frontend teams to handle errors gracefully.

Federation v2 adds another layer of complexity. Without proper @key resolution and @shareable field management, your subgraphs become tightly coupled, defeating the purpose of federation. You end up with a distributed monolith that is harder to deploy than your original REST API. If your team is also exploring real-time features, check out implementing-graphql-subscriptions to understand how subscriptions interact with a migrated GraphQL schema.

How a Mid-Sized Platform Avoided the Federation Pit

Imagine a logistics platform with 200 REST endpoints. The team decides to migrate to GraphQL to give their frontend more flexibility. They start by wrapping /api/users/:id in a GraphQL resolver. It works. They wrap /api/orders. It works. They launch. Two weeks later, the P99 latency for the user profile endpoint spikes to 2 seconds. The database is thrashing. The issue? The resolver for orders inside the User type was firing a separate database query for every user in a list. This is the classic N+1 problem.

The team tries to fix it by adding a cache. Now they have stale data. Orders are showing as "paid" when they've been refunded. They realize they need DataLoader to batch and cache the requests. But integrating DataLoader into an existing codebase without a strategy is risky. They risk breaking the existing REST endpoints while refactoring the GraphQL resolvers.

A better approach is the Strangler Fig pattern combined with a strict migration workflow. By gradually routing traffic from REST to GraphQL while validating every step, the team can catch issues early. They use a DataLoader implementation to batch database calls, eliminating the N+1 problem. They implement Federation v2 with proper @key directives to ensure entity resolution across subgraphs. They run automated validation scripts to check for schema violations. ^[1] This structured approach prevents the latency spike and ensures backward compatibility. You can also look at the graphql-mastery-pack for deeper insights into schema design and resolver implementation.

What Changes Once the Migration Strategy Is Locked

Once you install this skill and follow the migration workflow, the chaos disappears. Your resolvers are no longer ad-hoc fetch calls. They are backed by production-grade DataLoader implementations that batch and cache database and REST calls. The N+1 problem is eliminated by design, not by accident.

Your schema is validated at every step. The included schema-validator.js uses @graphql-tools to parse your generated schema, enforce @key directives on entities, validate resolver signatures, and check for DataLoader usage. If you violate migration rules, the validator exits with code 1, preventing broken code from reaching production. Your error handling is RFC 9457 compliant out of the box, ensuring consistent error responses across all endpoints.

Backward compatibility is guaranteed. The Strangler Fig pattern allows you to route traffic gradually, testing each migrated endpoint against the original REST behavior. You can use the validation script to ensure compatibility test dependencies are present and running. Federation v2 subgraphs work seamlessly with @key entity resolution and @shareable fields, allowing your teams to own their domains without stepping on each other's toes. ^[1] This level of control transforms your migration from a risky rewrite into a safe, incremental evolution.

What's Inside the Migrating Rest To Graphql Pack

This skill provides everything you need to execute a systematic, safe migration. No guesswork. No missing pieces. Just a complete workflow with templates, scripts, validators, and references.

• skill.md — Orchestrates the REST-to-GraphQL migration strategy, defines phases (Strangler Fig, Federation v2, DataLoader integration, validation), and references all supporting templates, scripts, validators, references, and examples.
• templates/rest-datasource.ts — Production-grade Apollo RESTDataSource implementation for read-through caching, request deduplication, and error handling when bridging REST endpoints to GraphQL resolvers.
• templates/federation-subgraph.cs — HotChocolate Apollo Federation v2 subgraph template featuring @key entity resolution, @shareable fields, [ReferenceResolver] attributes, custom directive composition, and schema export configuration.
• templates/data-loader.ts — Production-grade DataLoader pattern implementation to batch and cache database/REST calls, eliminating N+1 query problems in GraphQL resolvers.
• references/canonical-knowledge.md — Embedded authoritative knowledge covering backward compatibility guarantees (V1 to V2), Apollo Connectors/RESTDataSource mechanics, Federation v2 directives (@key, @shareable, @override), DataLoader batching principles, and schema export/compatibility testing workflows.
• scripts/validate-migration.sh — Executable shell script that verifies project structure, runs the JS schema validator, checks for GraphQL schema export commands, and ensures compatibility test dependencies are present. Exits non-zero on failure.
• validators/schema-validator.js — Node.js programmatic validator using @graphql-tools to parse the generated schema, enforce @key directives on entities, validate resolver signatures, check DataLoader usage, and exit 1 if migration rules are violated.
• examples/worked-example.md — Step-by-step migration walkthrough of a real /api/users/:id REST endpoint to a Federation v2 GraphQL subgraph with DataLoader integration, including code diffs, testing commands, and backward compatibility checks.

Stop Guessing. Start Migrating with Confidence.

Don't let your migration become another production incident. Upgrade to Pro to install this skill and get the complete migration workflow. Stop writing ad-hoc adapters. Start shipping a GraphQL API that is fast, safe, and backward compatible. ^[1] If you need help with the core server setup, building-graphql-server is a great companion skill. graphql-mastery-pack offers additional depth for advanced schema design. implementing-graphql-subscriptions can help you add real-time capabilities once your migration is stable.