Skip to main content
skill CX Codex

rest-to-graphql-migrator — Claude Code skill: REST to GraphQL

rest-to-graphql-migrator — a skill that walks a REST API over to GraphQL one endpoint at a time, wrapping existing routes instead of rebuilding the backend.

MIT 277 installs ★ 64 updated 2026-01-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add patricio0312rev/skills --skill rest-to-graphql-migrator -a claude-code
Open on GitHub

What rest-to-graphql-migrator does

The skill starts by cataloguing the REST endpoints you already have, then designs a GraphQL schema from them, adds a data source that talks to the old routes, and moves traffic over endpoint by endpoint. Old clients keep hitting REST until you retire a route.

Three migration paths are laid out: a wrapper for a fast start with no backend changes, a gradual move for large APIs already in production, and a full rewrite when the service is being rebuilt anyway. The samples are TypeScript and use Apollo's RESTDataSource — a class with baseURL from REST_API_URL, an auth header set in willSendRequest, one method per REST verb, and transforms that turn user_name into username and created_at into a Date.

Caching gets its own example: ttl: 3600 on reads, plus a this.delete call inside the update mutation to drop the cached entry. Skip that invalidation and getProduct keeps returning the old record. A DataLoader section covers the other weak spot — nested posts and comments fire one REST call per parent, so batching is what keeps the wrapper out of N+1 territory.

What it helps with

  • wrap an existing REST API in GraphQL without touching the backend
  • turn a list of REST endpoints into a GraphQL schema
  • ship one migrated endpoint at a time while old clients stay on REST
  • batch nested lookups with DataLoader to avoid N+1 calls
  • invalidate a cached REST data source on mutations

Example prompts for the agent

  • Map GET /api/users and the rest of the user routes to a GraphQL schema and show me the resolvers.
  • Wrap the products API in a RESTDataSource with ttl: 3600 and cache invalidation on update.
  • Add a DataLoader for nested posts and comments so requests stop fanning out to REST.

How to install rest-to-graphql-migrator

1Skills CLI (Vercel)

npx skills add patricio0312rev/skills --skill rest-to-graphql-migrator -a claude-code

2Manually: put the files in place

~/.claude/skills/rest-to-graphql-migrator/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/rest-to-graphql-migrator/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about rest-to-graphql-migrator

How do I install rest-to-graphql-migrator in Claude Code?

Run npx skills add patricio0312rev/skills --skill rest-to-graphql-migrator -a claude-code. The skill file lands at ~/.claude/skills/rest-to-graphql-migrator/SKILL.md.

What does rest-to-graphql-migrator do?

It runs a REST to GraphQL migration step by step: document endpoints, design the schema, build the data source, write resolvers, then move one route at a time and sunset REST.

Which migration strategy should I pick?

The wrapper suits a quick start with no backend edits. Gradual fits large APIs already in production, and a rewrite makes sense when the service is being built fresh.

Source text

SKILL.md · MIT
---
name: rest-to-graphql-migrator
description: Migrates REST APIs to GraphQL incrementally with schema stitching, REST datasources, and gradual endpoint migration. Use when users request "migrate to GraphQL", "REST to GraphQL", "GraphQL wrapper", or "API modernization".
---

# REST to GraphQL Migrator

Incrementally migrate REST APIs to GraphQL without breaking existing clients.

## Core Workflow

1. **Analyze REST endpoints**: Document existing API
2. **Design GraphQL schema**: Map REST to types
3. **Create REST data source**: Wrap existing endpoints
4. **Implement resolvers**: Connect to REST
5. **Migrate incrementally**: One endpoint at a time
6. **Deprecate REST**: Gradual sunset

## Migration Strategies

### Strategy Comparison

| Strategy | Best For | Complexity |
|----------|----------|------------|
| Wrapper | Quick start, no backend changes | Low |
| Gradual | Large APIs, production systems | Medium |
| Rewrite | Greenfield opportunity | High |

## REST Data Source Wrapper

### Apollo RESTDataSource

```typescript
// datasources/users.datasource.ts
import { RESTDataSource } from '@apollo/datasource-rest';

export class UsersAPI extends RESTDataSource {
  override baseURL = process.env.REST_API_URL;

  // Add auth header
  override willSendRequest(_path: string, request: AugmentedRequest) {
    request.headers['Authorization'] = this.context.token;
  }

  // GET /api/users
  async getUsers(params?: { page?: number; limit?: number }) {
    const query = new URLSearchParams();
    if (params?.page) query.set('page', String(params.page));
    if (params?.limit) query.set('limit', String(params.limit));

    return this.get<User[]>(`/api/users?${query}`);
  }

  // GET /api/users/:id
  async getUser(id: string) {
    return this.get<User>(`/api/users/${id}`);
  }

  // POST /api/users
  async createUser(input: CreateUserInput) {
    return this.post<User>('/api/users', { body: input });
  }

  // PATCH /api/users/:id
  async updateUser(id: string, input: UpdateUserInput) {
    return this.patch<User>(`/api/users/${id}`, { body: input });
  }

  // DELETE /api/users/:id
  async deleteUser(id: string) {
    await this.delete(`/api/users/${id}`);
    return true;
  }

  // GET /api/users/:id/posts
  async getUserPosts(userId: string) {
    return this.get<Post[]>(`/api/users/${userId}/posts`);
  }
}
```

### Map REST to GraphQL Types

```typescript
// REST Response
interface RESTUser {
  id: number;
  user_name: string;
  email_address: string;
  created_at: string;
  profile_image_url: string | null;
}

// GraphQL Type (camelCase, proper types)
interface User {
  id: string;
  username: string;
  email: string;
  createdAt: Date;
  avatar: string | null;
}

// Transformer
function transformUser(restUser: RESTUser): User {
  return {
    id: String(restUser.id),
    username: restUser.user_name,
    email: restUser.email_address,
    createdAt: new Date(restUser.created_at),
    avatar: restUser.profile_image_url,
  };
}
```

### Data Source with Caching

```typescript
// datasources/products.datasource.ts
export class ProductsAPI extends RESTDataSource {
  override baseURL = process.env.REST_API_URL;

  // Cache for 1 hour
  private cacheOptions = { ttl: 3600 };

  async getProduct(id: string) {
    const data = await this.get<RESTProduct>(`/api/products/${id}`, {
      cacheOptions: this.cacheOptions,
    });
    return transformProduct(data);
  }

  async getProducts(filters: ProductFilters) {
    const params = new URLSearchParams();
    Object.entries(filters).forEach(([key, value]) => {
      if (value !== undefined) params.set(key, String(value));
    });

    const data = await this.get<RESTProduct[]>(`/api/products?${params}`);
    return data.map(transformProduct);
  }

  // Bust cache on mutation
  async updateProduct(id: string, input: UpdateProductInput) {
    const data = await this.patch<RESTProduct>(`/api/products/${id}`, {
      body: transformToREST(input),
    });

    // Invalidate cache
    this.delete(`/api/products/${id}`);

    return transformProduct(data);
  }
}
```

## GraphQL Schema Design

### Schema from REST Endpoints

```graphql
# Map REST endpoints to GraphQL

# REST: GET /api/users
# REST: GET /api/users/:id
# REST: POST /api/users
# REST: PATCH /api/users/:id
# REST: DELETE /api/users/:id

type User {
  id: ID!
  username: String!
  email: String!
  avatar: String
  createdAt: DateTime!
  # Nested resource: GET /api/users/:id/posts
  posts: [Post!]!
  # Nested resource: GET /api/users/:id/comments
  comments: [Comment!]!
}

type Query {
  # GET /api/users
  users(page: Int, limit: Int): [User!]!
  # GET /api/users/:id
  user(id: ID!): User
}

type Mutation {
  # POST /api/users
  createUser(input: CreateUserInput!): User!
  # PATCH /api/users/:id
  updateUser(id: ID!, input: UpdateUserInput!): User!
  # DELETE /api/users/:id
  deleteUser(id: ID!): Boolean!
}

input CreateUserInput {
  username: String!
  email: String!
  password: String!
}

input UpdateUserInput {
  username: String
  email: String
  avatar: String
}
```

## Resolvers with REST Backend

```typescript
// resolvers/user.resolvers.ts
import { Resolvers } from '../generated/types';

export const userResolvers: Resolvers = {
  Query: {
    users: async (_, { page, limit }, { dataSources }) => {
      const users = await dataSources.usersAPI.getUsers({ page, limit });
      return users.map(transformUser);
    },

    user: async (_, { id }, { dataSources }) => {
      try {
        const user = await dataSources.usersAPI.getUser(id);
        return transformUser(user);
      } catch (error) {
        if (error.extensions?.response?.status === 404) {
          return null;
        }
        throw error;
      }
    },
  },

  Mutation: {
    createUser: async (_, { input }, { dataSources }) => {
      const user = await dataSources.usersAPI.createUser(
        transformInputToREST(input)
      );
      return transformUser(user);
    },

    updateUser: async (_, { id, input }, { dataSources }) => {
      const user = await dataSources.usersAPI.updateUser(
        id,
        transformInputToREST(input)
      );
      return transformUser(user);
    },

    deleteUser: async (_, { id }, { dataSources }) => {
      return dataSources.usersAPI.deleteUser(id);
    },
  },

  User: {
    // Resolve nested resources
    posts: async (parent, _, { dataSources }) => {
      const posts = await dataSources.usersAPI.getUserPosts(parent.id);
      return posts.map(transformPost);
    },

    comments: async (parent, _, { dataSources }) => {
      const comments = await dataSources.usersAPI.getUserComments(parent.id);
      return comments.map(transformComment);
    },
  },
};
```

## DataLoader for N+1 Prevention

```typescript
// loaders/user.loader.ts
import DataLoader from 'dataloader';
import { UsersAPI } from '../datasources/users.datasource';

export function createUserLoader(usersAPI: UsersAPI) {
  return new DataLoader<string, User>(async (ids) => {
    // Batch REST calls or use batch endpoint if available
    // Option 1: Parallel individual calls
    const users = await Promise.all(
      ids.map((id) => usersAPI.getUser(id).catch(() => null))
    );
    return ids.map((id) => users.find((u) => u?.id === id) || null);

    // Option 2: Use batch endpoint if available
    // const users = await usersAPI.getUsersByIds([...ids]);
    // return ids.map(id => users.find(u => u.id === id) || null);
  });
}

// Usage in resolver
User: {
  author: async (parent, _, { loaders }) => {
    return loaders.users.load(parent.authorId);
  },
}
```

## Incremental Migration

### Phase 1: Wrapper Layer

```typescript
// Start with GraphQL wrapping REST
// All data still flows through REST API

const server = new ApolloServer({
  typeDefs,
  resolvers,
  dataSources: () => ({
    usersAPI: new UsersAPI(),
    postsAPI: new PostsAPI(),
    commentsAPI: new CommentsAPI(),
  }),
});
```

### Phase 2: Direct Database Access

```typescript
// Migrate critical paths to direct DB
// Keep REST as fallback

const userResolvers: Resolvers = {
  Query: {
    user: async (_, { id }, { dataSources, db }) => {
      // Try direct DB first
      const user = await db.user.findUnique({ where: { id } });
      if (user) return user;

      // Fallback to REST
      return dataSources.usersAPI.getUser(id);
    },
  },
};
```

### Phase 3: Full Migration

```typescript
// All data from database
// REST endpoints deprecated

const userResolvers: Resolvers = {
  Query: {
    user: async (_, { id }, { db }) => {
      return db.user.findUnique({
        where: { id },
      });
    },

    users: async (_, { page = 1, limit = 20 }, { db }) => {
      return db.user.findMany({
        skip: (page - 1) * limit,
        take: limit,
      });
    },
  },

  User: {
    posts: async (parent, _, { loaders }) => {
      return loaders.postsByAuthor.load(parent.id);
    },
  },
};
```

## Error Handling

```typescript
// Map REST errors to GraphQL errors
import { GraphQLError } from 'graphql';

function handleRESTError(error: any): never {
  const status = error.extensions?.response?.status;
  const body = error.extensions?.response?.body;

  switch (status) {
    case 400:
      throw new GraphQLError(body?.message || 'Bad request', {
        extensions: { code: 'BAD_USER_INPUT' },
      });

    case 401:
      throw new GraphQLError('Not authenticated', {
        extensions: { code: 'UNAUTHENTICATED' },
      });

    case 403:
      throw new GraphQLError('Not authorized', {
        extensions: { code: 'FORBIDDEN' },
      });

    case 404:
      throw new GraphQLError('Resource not found', {
        extensions: { code: 'NOT_FOUND' },
      });

    case 409:
      throw new GraphQLError(body?.message || 'Conflict', {
        extensions: { code: 'CONFLICT' },
      });

    default:
      throw new GraphQLError('Internal server error', {
        extensions: { code: 'INTERNAL_SERVER_ERROR' },
      });
  }
}

// Usage in resolver
async getUser(id: string) {
  try {
    return await this.dataSources.usersAPI.getUser(id);
  } catch (error) {
    handleRESTError(error);
  }
}
```

## Schema Stitching

### Combine Multiple REST Services

```typescript
// Stitch multiple REST backends
import { stitchSchemas } from '@graphql-tools/stitch';

const usersSchema = makeExecutableSchema({
  typeDefs: usersTypeDefs,
  resolvers: usersResolvers,
});

const productsSchema = makeExecutableSchema({
  typeDefs: productsTypeDefs,
  resolvers: productsResolvers,
});

const ordersSchema = makeExecutableSchema({
  typeDefs: ordersTypeDefs,
  resolvers: ordersResolvers,
});

const gatewaySchema = stitchSchemas({
  subschemas: [
    { schema: usersSchema },
    { schema: productsSchema },
    { schema: ordersSchema },
  ],
  typeMergingOptions: {
    // Configure type merging
  },
});
```

## Deprecation Strategy

```graphql
type Query {
  # Old endpoint - deprecated
  getUser(id: ID!): User @deprecated(reason: "Use user(id:) instead")

  # New endpoint
  user(id: ID!): User
}

type User {
  # Deprecated field with migration path
  userName: String @deprecated(reason: "Use username instead")
  username: String!
}
```

## Best Practices

1. **Start with wrapper**: Don't rewrite, wrap
2. **Migrate incrementally**: One endpoint at a time
3. **Use DataLoader**: Prevent N+1 queries
4. **Transform data shapes**: Improve API design
5. **Add caching**: Reduce REST API calls
6. **Handle errors properly**: Map REST errors to GraphQL
7. **Deprecate gradually**: Give clients time to migrate
8. **Monitor both**: Track REST and GraphQL usage

## Output Checklist

Every REST to GraphQL migration should include:

- [ ] REST endpoints documented
- [ ] GraphQL schema designed
- [ ] RESTDataSource implementations
- [ ] Data transformers (REST ↔ GraphQL)
- [ ] DataLoader for batching
- [ ] Error handling and mapping
- [ ] Caching strategy
- [ ] Incremental migration plan
- [ ] Deprecation annotations
- [ ] Client migration guide

© patricio0312rev · MIT · patricio0312rev/skills

Similar skills

All skills for Backend and APIs →

From the same set148

The whole set →
typescript-strict-migrator typescript-strict-migrator moves a TypeScript codebase to strict mode one compiler flag at a time: audit the errors, then turn on noImplicitAny, strictNullChecks and the rest. Handy when strict: true throws too much at once. CX Codex +1 280installs migration-planner migration-planner turns a database or platform move into ordered phases with feature flags, dual writes, backfill and checks, plus a way back from each step. CX Codex +1 279installs code-formatter-installer code-formatter-installer installs Prettier, ESLint, EditorConfig and git hooks, then wires them into CI so the whole team formats code the same way. CX Codex +1 278installs caching-strategist caching-strategist turns a vague “add caching” request into named layers, key layouts, TTL values and invalidation rules, with TypeScript samples for Redis and CDN. CX Codex +1 278installs insomnia-collection-generator insomnia-collection-generator scans Express, Fastify, and Next.js routes to generate an Insomnia v4 collection export file with organized workspaces, folders, and environments. CX Codex +1 277installs security-pr-checklist-skill security-pr-checklist-skill builds a repeatable security checklist for pull requests. Use it to structure code reviews, required checks, and CI security gates. CX Codex +1 276installs design-to-component-translator The design-to-component-translator skill turns Figma specs into React components with design tokens, responsive rules, and interaction states for implementing designs in code. CX Codex +1 276installs secrets-env-manager secrets-env-manager validates environment variables in CI workflows, enforces secret masking, and catches leaked keys early. CX Codex +1 276installs

Project sponsors

Companies that keep this analytics open