GraphQL - REST API와 차이

안녕하세요. 벌써 금요일이네요. 시간이 빨리가는 것 같습니다.

깁스 풀고 보호대 착용했으니 본격적으로 다시 운동을 시작하고 싶은데 뭐부터 시작해야할지 감이 안잡히네요. 발목 가동 범위도 줄어서 쉽지 않은 것 같아요. 조금 더 고민하고 생각해봐야겠네요. 자, 그럼 학습 시작해보겠습니다.

---

GraphQL

GraphQL은 메타(페이스북)가 개발한 API를 위한 오픈소스 쿼리 언어입니다. 클라이언트가 필요한 데이터를 직접 지정해서 요청할 수 있는 API 질의 언어입니다.

REST API에서는 서버가 정해둔 endpoint에 요청을 보내고, 서버가 정해둔 응답 구조를 받습니다. 반면 GraphQL에서는 클라이언트가 필요한 field를 직접 선택해서 요청할 수 있습니다.

 

즉, GraphQL은 "서버가 정해둔 응답을 그대로 받는 방식"이 아니라, "클라이언트가 필요한 데이터 형태를 요청하는 방식"에 가깝습니다.

 

GraphQL

query {
  book(id: 1) {
    title
    author
  }
}

JSON

{
  "data": {
    "book": {
      "title": "GraphQL 입문",
      "author": "user1"
    }
  }
}

 

위의 예시에서 클라이언트는 'book' 데이터 중 'title'과 'author'만 요청했습니다. 서버는 요청 받은 field에 맞춰 필요한 데이터만 응답합니다.

 

REST API의 한계

REST API는 리소스 중심으로 API를 설계하기 때문에 구조가 직관적이고 HTTP Method와 잘 어울립니다. 예를 들어 게시글 목록 조회, 게시글 상세 조회, 댓글 작성 같은 기능을 각각 endpoint로 나누어 설계할 수 있습니다.

 

GET /posts

GET /posts/1

GET /posts/1/comment

GET /users/1

 

하지만 화면이 복잡해지면 클라이언트가 원하는 데이터를 한 번에 가져오기 어려운 경우가 생길 수 있습니다. 

예를 들어 게시글 상세 화면에서 게시글 정보, 작성자 정보, 댓글 목록, 좋아요 수를 모두 보여줘야 한다면 여러 API를 호출해야 할 수 있습니다.

 

GET /posts/1

GET /users/1

GET /posts/1/comments

GET posts/1/likes

또는 반대로 하나의 API 응답에 클라이언트가 사용하지 않는 데이터까지 포함되어 불필요한 데이터 전송이 발생할 수 있습니다. 이러한 문제를 각각 Under-fetching과 Over-fetching이라고 합니다.

 

Over-fetching과 Under-fetching

Over-fetching

Over-fetching은 클라이언트가 필요한 데이터보다 더 많은 데이터를 응답받는 상황입니다. 

예를 들어 클라이언트는 게시글 제목과 작성자 이름만 필요하지만, 서버 API가 게시글 내용, 작성일, 수정일, 조회수, 태그, 댓글 수까지 함께 응답한다면 필요하지 않은 데이터까지 전달받게 됩니다. 

{
  "id": 1,
  "title": "GraphQL이란?",
  "content": "본문 내용...",
  "createdAt": "2026-05-29",
  "updatedAt": "2026-05-29",
  "viewCount": 120,
  "author": {
    "id": 3,
    "name": "user1",
    "email": "user1@test.com"
  }
}

이 중 클라이언트가 실제로 사용하는 값이 'title'과 'author.name'뿐이라면 나머지 데이터는 불필요하게 전달된 것입니다.

 

Under-fetching

Under-fetching은 하나의 API 호출만으로 필요한 데이터를 충분히 가져오지 못해 여러 API를 추가로 호출해야 하는 상황입니다.

예를 들어 게시글 상세 화면에서 게시글 정보뿐 아니라 작성자 정보와 댓글 목록도 필요하다면 REST API에서는 여러 endpoint를 호출해야 할 수 있습니다.

GET /posts/1

GET /users/3

GET /posts/1/comments

이 경우 클라이언트는 화면 하나를 구성하기 위해 여러 번 서버와 통신해야 하고, API 호출 흐름도 복잡해질 수 있습니다.

 

GraphQL의 기본 구조

GraphQL은 보통 하나의 endpoint를 사용합니다.

POST /graphql

REST API가 여러 endpoint를 리소스별로 나누는 것과 달리, GraphQL은 하나의 endpoint에 Query를 전달하고 서버는 Query에 맞는 데이터를 응답합니다.

query {
  post(id: 1) {
    title
    author {
      name
    }
    comments {
      content
      writer {
        name
      }
    }
  }
}

 위 요청을 게시글 제목, 작성자 이름, 댓글 내용, 댓글 작성자 이름을 한 번에 요청합니다. 클라이언트가 필요한 데이터 구조를 직접 작성하기 때문에 여러 API를 호출하지 않고도 화면에 필요한 데이터를 가져올 수 있습니다. 

 

Query, Mutation, Schema

Query

Query는 데이터를 조회할 때 사용합니다. REST API의 GET 요청과 비슷한 역할을 합니다.

query {
  user(id: 1) {
    id
    name
    email
  }
}

 

Mutation

Mutation은 데이터 생성, 수정, 삭제할 때 사용합니다. REST API의 POST, PUT, PATCH, DELETE와 비슷한 역할을 합니다.

mutation {
  createPost(input: {
    title: "GraphQL 정리"
    content: "GraphQL은 필요한 데이터를 직접 요청할 수 있습니다."
  }) {
    id
    title
  }
}

 

Schema

Schema는 GraphQL API에서 어떤 데이터를 요청할 수 있고, 어떤 타입을 반환하는지 정의하는 구조입니다. GraphQL 서버는 Schema를 기준으로 클라이언트의 요청이 유효한지 확인하고, 요청된 데이터의 형태에 맞게 응답합니다.

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
}

type User {
  id: ID!
  name: String!
}

type Query {
  post(id: ID!): Post
}

위 Schena는 'post'라는 Query를 통해 특정 게시글을 조회할 수 있고, 게시글 'id', 'title', 'content', 'author' 정보를 가진다는 것을 정의합니다.

 

GraphQL의 장점과 단점

장점

1. 필요한 데이터만 요청 가능
   • 클라이언트가 필요한 field만 선택해 요청할 수 있음
2. 여러 데이터를 한 번에 조회 가능
   • 하나의 Query로 연관된 데이터를 함께 요청할 수 있음
3. API 응답 구조 예측 가능
   • 요청한 구조와 비슷한 형태로 응답이 내려옴
4. 클라이언트 변화에 유연함
   • 화면마다 필요한 데이터가 달라도 Query를 조정해 대응 가능
5. 타입 기반 Schema
   • 요청 가능한 데이터 구조를 명확히 정의할 수 있음

단점

1. 서버 구현 복잡도 증가
   • Schema, Resolver, 타입 정의 등을 설계해야 함
2. 복잡한 Query 문제
   • 클라이언트가 너무 깊거나 무거운 Query를 요청할 수 있음
3. 캐싱이 REST보다 까다로움 
   • REST처럼 URL 단위 캐싱을 적용하기 어려울 수 있음
4. N+1 문제 가능성
   • 연관 데이터를 Resolver에서 반복 조회하면 성능 문제가 생길 수 있음

 

REST API와 GraphQL 비교

REST API는 리소스 중심으로 단순하고 명확하게 API를 설계하기 좋습니다. 반면 GraphQL은 클라이언트가 필요한 데이터 구조를 직접 요청할 수 있어 화면별 데이터 요구사항이 다양한 서비스에서 유리할 수 있습니다.

구분	REST API	GraphQL
요청 방식	여러 endpoint 사용	보통 하나의 endpoint 사용
데이터 응답	서버가 정한 구조로 응답	클라이언트가 요청한 구조로 응답
데이터 조회	필요한 데이터에 따라 여러 API 호출 가능	하나의 Query로 연관 데이터 조회 가능
Over-fetching	발생할 수 있음	줄일 수 있음
Under-fetching	발생할 수 있음	줄일 수 있음
캐싱	HTTP 캐싱과 잘 어울림	별도 캐싱 전략 필요
설계 기준	리소스 중심	Schema와 타입 중심

 

Apollo란?

Apollo는 GraphQL을 더 쉽게 사용할 수 있도록 도와주는 도구입니다.

클라이언트에서는 Apollo Client를 사용해 GraphQL Query를 보내고, 응답 데이터를 캐싱하거나 상태 관리와 함께 사용할 수 있습니다. 서버에서는 Apollo Server를 사용해 GraphQL Schema와 Resolver를 구성할 수 있습니다. 

 

즉, Apollo는 GraphQL 자체가 아니라 GraphQL을 실제 애플리케이션에서 더 편하게 사용할 수 있도록 도와주는 라이브러리 도구 모음에 가깝습니다.

---

오늘은 GraphQL과 REST API와의 차이에 대해 정리했습니다. 간략하게 알아간 정도라서 추가적인 학습이 필요한 경우 다른 블로그를 더 참조하는게 좋을 것 같습니다. GraphQL을 사용하게 될지는 모르겠지만, 만약 사용하게 된다면 포스팅하도록 하겠습니다. 수고하셨습니다.