Migrating from REST API to GraphQL

Tip

Prefer a no-big-bang approach? This guide covers full migration. For a phased strategy where FraiseQL runs alongside your REST API while you migrate domain by domain — with rollback at every step — see the Incremental Migration Guide.

Migrating from REST API to GraphQL

This guide shows how to migrate from traditional REST APIs to GraphQL using FraiseQL.

Why Migrate?

Problem	REST	GraphQL
Over-fetching	GET /users returns all fields	Query only needed fields
Under-fetching	Must chain API calls	Get all data in one request
Versioning	/v1/, /v2/ endpoints	Single endpoint, evolves safely
Documentation	Separate docs	Self-documenting via schema
Client bloat	Multiple endpoints	Single endpoint
Real-time	WebSocket polling	Native subscriptions

Conversion Examples

Getting a User with Posts

REST (Over/under-fetching)

# Request 1: Get user (gets all fields)
GET /api/users/123
# Response: 500 bytes with fields you don't need

# Request 2: Get user's posts
GET /api/users/123/posts
# Response: another round-trip

# Request 3: Get post comments
GET /api/posts/456/comments
# Total: 3 requests, lots of unused data

GraphQL (Exact data needed)

query {
  user(id: 123) {
    name
    email
    posts {
      title
      comments {
        text
      }
    }
  }
}
# Single request, exactly what you need

Step-by-Step Conversion

1. Document REST Endpoints

   Map out every existing REST endpoint before you begin:

   GET /api/users              -> Get all users
   GET /api/users/:id          -> Get user
   POST /api/users             -> Create user
   PUT /api/users/:id          -> Update user
   DELETE /api/users/:id       -> Delete user
   GET /api/users/:id/posts    -> Get user's posts
   GET /api/posts              -> Get all posts
   GET /api/posts/:id          -> Get post
   POST /api/posts             -> Create post

2. Map Endpoints to GraphQL Operations

   REST Endpoint	GraphQL Equivalent
   GET /users	query { users { ... } }
   GET /users/:id	query { user(id: "...") { ... } }
   GET /users?status=active	query { users(where: { status: { _eq: "active" } }) { ... } }
   POST /users	mutation { createUser(input: { ... }) { ... } }
   PUT /users/:id	mutation { updateUser(id: "...", input: { ... }) { ... } }
   DELETE /users/:id	mutation { deleteUser(id: "...") }
   GET /users/:id/posts	query { user(id: "...") { posts { ... } } }

3. Define FraiseQL Types and SQL Views

   Each REST resource becomes a FraiseQL type backed by a SQL view (v_*). The FraiseQL Rust binary reads data directly from these views — there are no Python resolvers at runtime.

   Note

   The SQL examples in this guide use PostgreSQL syntax. If you are using MySQL or SQLite, the view syntax differs slightly — consult your database’s documentation for CREATE VIEW and stored procedure equivalents.

   REST (Python/Flask)

   routes/users.py

   @app.get("/api/users")
   def get_users():
       return {"users": User.all()}
   
   @app.get("/api/users/{user_id}")
   def get_user(user_id: int):
       return {"user": User.get(user_id)}
   
   @app.post("/api/users")
   def create_user(data: UserInput):
       return {"user": User.create(data)}

   FraiseQL (Python)

   @fraiseql.type
   class User:
       id: ID
       name: str
       email: str
       posts: list['Post']
   
   # Reads from SQL view v_user
   @fraiseql.query(sql_source="v_user")
   def users(limit: int = 50) -> list[User]:
       """GET /users -> query { users { ... } }"""
       pass
   
   @fraiseql.query(sql_source="v_user")
   def user(id: ID) -> User:
       """GET /users/:id -> query { user(id: ...) { ... } }"""
       pass
   
   # Calls database function fn_create_user
   @fraiseql.mutation(sql_source="fn_create_user")
   def create_user(name: str, email: str) -> User:
       """POST /users -> mutation { createUser(...) { ... } }"""
       pass

   FraiseQL (TypeScript)

   import { type, query, mutation, ID } from 'fraiseql';
   
   @type()
   class User {
       id!: ID;
       name!: string;
       email!: string;
       posts!: Post[];
   }
   
   // Reads from SQL view v_user
   @query({ sqlSource: 'v_user' })
   function users(limit: number = 50): Promise<User[]> {
       return Promise.resolve([]);
   }
   
   @query({ sqlSource: 'v_user' })
   function user(id: ID): Promise<User> {
       return Promise.resolve({} as User);
   }
   
   // Calls database function fn_create_user
   @mutation({ sqlSource: 'fn_create_user' })
   function createUser(name: string, email: string): Promise<User> {
       return Promise.resolve({} as User);
   }

   FraiseQL (Go)

   import "github.com/fraiseql/fraiseql-go"
   
   type User struct {
       ID    fraiseql.ID `fraiseql:"id"`
       Name  string      `fraiseql:"name"`
       Email string      `fraiseql:"email"`
       Posts []Post      `fraiseql:"posts"`
   }
   
   func init() {
       // Reads from SQL view v_user
       fraiseql.Query("users", fraiseql.QueryConfig{
           SQLSource: "v_user",
       }, func(args fraiseql.Args) ([]User, error) { return nil, nil })
   
       fraiseql.Query("user", fraiseql.QueryConfig{
           SQLSource: "v_user",
       }, func(args fraiseql.Args) (User, error) { return User{}, nil })
   
       // Calls database function fn_create_user
       fraiseql.Mutation("createUser", fraiseql.MutationConfig{
           SQLSource: "fn_create_user",
       }, func(args fraiseql.Args) (User, error) { return User{}, nil })
   }

4. Build GraphQL API Alongside REST

   Run both systems in parallel during migration. FraiseQL can serve specific endpoints while your existing REST API handles the rest — you do not need to migrate everything at once.

   Tip

   Incremental migration: Start by migrating your highest-traffic or most pain-prone REST endpoints to FraiseQL first. Your existing REST API continues to handle all other routes unchanged. Once each GraphQL endpoint is stable, decommission the corresponding REST route. There is no requirement to migrate all endpoints simultaneously.

   A typical routing setup during migration:

   /graphql          → FraiseQL (migrated endpoints)
   /api/users        → FraiseQL (migrated)
   /api/posts        → FraiseQL (migrated)
   /api/reports      → Legacy REST handler (not yet migrated)
   /api/webhooks     → Legacy REST handler (not yet migrated)

   Route a percentage of traffic to the new GraphQL endpoint while keeping REST available as a fallback.

5. Update Client Code

   REST Client

   // Before
   async function getUser(userId: number) {
     const userRes = await fetch(`/api/users/${userId}`);
     const user = await userRes.json();
   
     const postsRes = await fetch(`/api/users/${userId}/posts`);
     const posts = await postsRes.json();
   
     return { ...user, posts: posts.posts };
   }

   GraphQL Client

   // After
   async function getUser(userId: number) {
     const response = await client.query(`
       query {
         user(id: ${userId}) {
           name
           email
           posts {
             id
             title
           }
         }
       }
     `);
   
     return response.data.user;
   }

6. Route Traffic Gradually

   Week 1-2: Build GraphQL alongside REST
   Week 3-4: Route 50% of traffic to GraphQL
   Week 5-6: Route 100% to GraphQL
   Week 7+: Decommission REST

7. Decommission REST Endpoints

   Once all clients are migrated and GraphQL is confirmed stable, remove the REST endpoints and clean up related dependencies.

Request/Response Comparison

REST (3 requests)

# Request 1
GET /api/users/123
# Response includes unused fields: createdAt, updatedAt

# Request 2
GET /api/users/123/posts
# Response includes all post fields

# Request 3
GET /api/posts/456/comments

# Total: 3 requests + latency

GraphQL (1 request)

POST /graphql
Content-Type: application/json

{
  "query": "query { user(id: 123) { name email posts { title comments { text } } } }"
}

# Response
{
  "data": {
    "user": {
      "name": "Alice",
      "email": "alice@example.com",
      "posts": [
        {
          "title": "First Post",
          "comments": [
            { "text": "Nice!" },
            { "text": "Great article!" }
          ]
        }
      ]
    }
  }
}

# Total: 1 request, exact data needed

Pagination

REST

GET /api/users?limit=10&offset=20

GraphQL

query {
  users(limit: 10, offset: 20) {
    id
    name
  }
}

Filtering

REST

GET /api/posts?status=published&author_id=123&sort=-created_at

GraphQL

query {
  posts(
    status_eq: "published"
    author_id_eq: 123
    orderBy: "created_at DESC"
  ) {
    id
    title
  }
}

Error Handling

REST (HTTP Status Codes)

404 Not Found
400 Bad Request
500 Internal Server Error
401 Unauthorized

GraphQL (200 OK + error in body)

{
  "errors": [
    {
      "message": "User not found",
      "extensions": {
        "code": "NOT_FOUND",
        "userId": "123"
      }
    }
  ]
}

FraiseQL includes helpful error codes and context in all error responses.

Subscriptions (New Capability)

REST has no good real-time support. FraiseQL provides native subscriptions via WebSocket and NATS:

subscription {
  postCreated {
    id
    title
    author {
      name
    }
  }
}

Note

FraiseQL subscriptions are backed by NATS messaging. When a PostgreSQL function (fn_*) completes a write, FraiseQL automatically publishes the event to subscribed clients — no polling required.

Performance Impact

Metric	REST	GraphQL
Requests per view	3+	1
Response time	200-500ms	50-100ms
Unused data	50-70%	0%
Data joining	Client-side	Server-side (SQL views)

Deployment Simplification

REST:

Multiple endpoints
/api/v1/users
/api/v1/posts
/api/v1/comments
/api/v2/users  (new version!)
/api/v2/posts

GraphQL:

Single endpoint
/graphql
  (Schema evolves safely; clients request only what they need)

Migration Checklist

• Document all REST endpoints
• Map endpoints to GraphQL queries/mutations
• Write SQL views (v_*) for all read operations
• Write PostgreSQL functions (fn_*) for all write operations
• Define FraiseQL types and decorators
• Build GraphQL API alongside REST
• Update client code
• Performance test
• Route traffic gradually
• Decommission REST endpoints

Key Advantages of GraphQL

1. Single Request - Get all data in one call
2. Exact Data - No over/under-fetching
3. Self-Documenting - Schema is documentation
4. Subscriptions - Real-time updates
5. Evolves Safely - Add fields without breaking clients
6. Better Performance - Pre-compiled SQL views, automatic optimization

Prisma Migration

Migrating from Prisma ORM to FraiseQL.

Read guide

Apollo Migration

Migrating from Apollo Server to FraiseQL.

Read guide

Hasura Migration

Migrating from Hasura to FraiseQL.

Read guide

Getting Started

Learn FraiseQL fundamentals from scratch.

Read guide