How do I combine REST and GraphQL into a single API?

You generally don’t literally merge REST and GraphQL into one protocol. Instead, you expose one API surface that uses GraphQL as an aggregation layer over existing REST services.

Common architecture

Option 1: GraphQL in front of REST

This is the most common approach.

• Keep your existing REST endpoints/services
• Add a GraphQL server as a gateway
• GraphQL resolvers call the REST APIs behind the scenes
• Clients use GraphQL for flexible querying

Example flow:

Client
  -> GraphQL API
      -> REST User Service
      -> REST Orders Service
      -> REST Inventory Service

This works well when:

• you already have REST services
• you want to reduce over-fetching/under-fetching
• multiple frontend apps need different shapes of data

Example

Suppose you already have REST:

• GET /users/42
• GET /users/42/orders

You can expose GraphQL like:

type User {
  id: ID!
  name: String!
  orders: [Order!]!
}

type Order {
  id: ID!
  total: Float!
}

type Query {
  user(id: ID!): User
}

Resolvers:

const resolvers = {
  Query: {
    user: async (_, { id }, { dataSources }) => {
      return dataSources.userApi.getUser(id);
    }
  },
  User: {
    orders: async (user, _, { dataSources }) => {
      return dataSources.orderApi.getOrdersByUser(user.id);
    }
  }
};

Option 2: REST and GraphQL side by side

You can expose both:

• REST for simple CRUD and public integrations
• GraphQL for complex client-driven queries

Example:

• REST:
  • POST /payments
  • GET /health
  • GET /files/:id/download
• GraphQL:
  • dashboards
  • mobile app data
  • aggregated views

This is often the most practical hybrid model.

When REST is better

Use REST for:

• file uploads/downloads
• caching-friendly public resources
• simple webhook-style integrations
• operations with clear resource semantics
• endpoints external partners already expect

When GraphQL is better

Use GraphQL for:

• combining data from multiple services
• mobile/web clients with varying data needs
• nested, relational data
• reducing multiple round trips

Design advice

1. Don’t duplicate everything blindly

Avoid creating:

• a full REST API
• and a full GraphQL API
• for the exact same use cases

That doubles maintenance.

Instead:

• keep REST as system/service APIs
• use GraphQL as consumer-facing aggregation

2. Separate writes carefully

Mutations in GraphQL usually map to REST writes underneath.

Example:

type Mutation {
  createOrder(userId: ID!, productId: ID!): Order!
}

Resolver:

createOrder: async (_, args, { dataSources }) => {
  return dataSources.orderApi.createOrder(args);
}

3. Handle errors consistently

REST returns:

• HTTP status codes
• response bodies

GraphQL returns:

• data
• errors

So define a clear mapping strategy from REST failures into GraphQL errors.

4. Watch performance

A naive GraphQL layer over REST can create N+1 request problems.

Use:

• batching
• caching
• DataLoader-style patterns
• backend aggregation where possible

5. Keep auth centralized

Usually:

• authenticate once at the gateway
• pass identity/claims to REST services

Good hybrid pattern

A strong practical setup is:

• REST internally or for operational endpoints
• GraphQL externally for app clients

For example:

Frontend apps -> GraphQL gateway -> REST microservices
Ops/integrations -> REST endpoints

If you want a “single API”

If by “single API” you mean one domain like:

• api.example.com/graphql
• api.example.com/rest/...

then yes, absolutely. Put both behind the same gateway/domain.

Example:

api.example.com/graphql
api.example.com/v1/users
api.example.com/v1/orders

That gives one platform without forcing one style.

Recommendation

If you already have REST, the best path is usually:

1. Keep REST services
2. Add GraphQL as a facade/gateway
3. Use REST for simple/system actions
4. Use GraphQL for client-shaped reads and aggregated workflows

If you want, I can also give you:

• a Node.js/Apollo example
• a NestJS hybrid architecture
• or a Spring Boot example for combining REST and GraphQL.