Home / AI / AI 용어사전 / GraphQL — REST 대신 원하는 데이터만 쏙 뽑는 API 방식

TERM

GraphQL — REST 대신 원하는 데이터만 쏙 뽑는 API 방식

게시일 2026-04-30수정일 2026-04-30

On this page

REST API를 쓰다 보면 필요 없는 데이터까지 통째로 받거나, 반대로 한 화면을 위해 API를 여러 번 호출해야 하는 상황이 생긴다. GraphQL은 이 문제를 "클라이언트가 원하는 것만 요청한다"는 원칙 하나로 해결한다.

정의

GraphQL은 2015년 Facebook(현 Meta)이 공개한 API 쿼리 언어이자 런타임이다. rest처럼 여러 엔드포인트를 두는 대신, 단일 엔드포인트(/graphql)에서 클라이언트가 필요한 필드를 명시적으로 지정해 정확히 그것만 받는다.

GraphQL의 핵심 아이디어는 데이터 형태를 클라이언트가 결정한다는 점이다. REST에서는 서버가 응답 구조를 고정하고 클라이언트가 거기서 필요한 것만 꺼내 쓴다. GraphQL에서는 클라이언트가 "이 필드, 저 필드만 줘"라고 명시하면 서버가 정확히 그것만 반환한다.

이 방식은 두 가지 고질적 문제를 해결한다. 필요 없는 데이터까지 받는 과도 수신(Overfetching)과, 여러 API를 연속 호출해야 하는 과소 수신(Underfetching)이다.

REST vs GraphQL 비교

같은 데이터를 요청하는 두 방식을 비교하면 차이가 명확해진다.

REST 방식 (여러 엔드포인트 호출):

# 1차 요청: 사용자 정보
GET /users/123
→ { id, name, email, address, phone, createdAt, ... }
  (name만 필요한데 전체 필드가 온다 — Overfetching)

# 2차 요청: 게시글 (별도 API 호출 필요 — Underfetching)
GET /users/123/posts
→ [{ id, title, content, authorId, tags, ... }]

GraphQL 방식 (단일 엔드포인트, 한 번의 요청):

query {
  user(id: "123") {
    name          # 이 필드만
    posts {
      title       # 이 필드만
    }
  }
}

# 응답: 요청한 필드만 정확히 반환
→ { user: { name: "홍길동", posts: [{ title: "글 제목" }] } }

한 번의 요청으로 여러 리소스를 가져오고, 불필요한 필드는 전혀 전송하지 않는다. 모바일 환경처럼 데이터 사용량이 민감한 경우 체감 효과가 크다.

스키마와 타입 시스템

GraphQL의 또 다른 강점은 강타입(Strongly Typed) 스키마다. 서버는 사용 가능한 모든 데이터 구조를 스키마로 명시하고, 클라이언트는 스키마를 보고 어떤 필드를 요청할 수 있는지 미리 안다.

type Article {
  id: ID!
  title: String!
  content: String!
  category: String
  publishedAt: String
  author: Author
}

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

type Query {
  articles(category: String): [Article]
  article(id: ID!): Article
}

type Mutation {
  createArticle(title: String!, content: String!): Article
}

스키마가 API 문서 역할을 겸한다. GraphiQL이나 Apollo Studio 같은 도구로 스키마를 탐색하고 실시간으로 쿼리를 테스트할 수 있다. typescript와 결합하면 쿼리 결과의 타입을 자동으로 생성해 타입 안전성도 확보된다.

AI 서비스에서 GraphQL 활용

AI 서비스가 복잡한 데이터 모델을 다룰 때 GraphQL이 적합한 이유가 있다.

헤드리스 CMS + AI 연동: Contentful, Sanity 같은 헤드리스 CMS는 GraphQL API를 제공한다. AI가 생성한 콘텐츠를 CMS에 저장하고, 프론트엔드에서 필요한 필드만 GraphQL로 조회한다.

AI 대시보드: AI 모델 메타데이터(이름·버전·성능 지표·비용)를 여러 컴포넌트에서 각기 다른 필드 조합으로 요청할 때 GraphQL이 효율적이다. REST였다면 컴포넌트마다 다른 엔드포인트를 만들거나 과도한 데이터를 받아야 한다.

서버리스 + AI: Next.js App Router에서 Supabase의 GraphQL 엔드포인트를 통해 AI 생성 데이터를 조회하는 패턴이 증가하고 있다. Supabase는 pg_graphql 확장으로 PostgreSQL 스키마에서 GraphQL API를 자동 생성한다.

REST가 더 적합한 경우: 단순한 CRUD 서비스, 파일 업로드, 캐싱이 중요한 공개 API에서는 REST가 더 단순하고 직관적이다. GraphQL 도입은 데이터 요구사항이 복잡하고 다양한 클라이언트(웹·앱·서드파티)가 존재할 때 효과가 크다.

정의

GraphQL은 Facebook(현 Meta)이 2012년 개발하고 2015년 오픈소스로 공개한 api 쿼리 언어이자 런타임이다. 클라이언트가 필요한 데이터의 구조를 직접 지정해 요청하면, 서버는 딱 그 형태로만 응답한다. 단일 엔드포인트(/graphql)로 모든 요청을 처리하며, SQL처럼 선언적 쿼리로 데이터를 다룬다는 점이 특징이다.

상세 설명

REST와의 핵심 차이

rest-api는 서버가 응답 형태를 결정한다. GET /users/123을 호출하면 서버가 정의한 사용자 객체 전체가 돌아온다. 클라이언트는 필요 없는 필드도 받아야 한다(Over-fetching).

반면 특정 페이지에서 여러 리소스가 필요하면 엔드포인트를 여러 번 호출해야 한다(Under-fetching).

GraphQL은 클라이언트가 원하는 형태를 쿼리로 명시한다.

# REST: GET /users/123 → 모든 필드 반환
# GraphQL: 원하는 필드만 지정
query {
  user(id: "123") {
    name
    avatarUrl
    posts(last: 3) {
      title
      publishedAt
    }
  }
}

이 쿼리 하나로 사용자 정보와 최근 게시글 3개를 한 번의 요청으로 가져온다. 서버는 name, avatarUrl, title, publishedAt만 반환한다.

타입 시스템과 스키마

GraphQL의 강점 중 하나는 강타입 스키마다. 서버는 제공 가능한 데이터 구조를 스키마(Schema)로 선언한다.

type User {
  id: ID!
  name: String!
  avatarUrl: String
  posts: [Post!]!
}

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

type Query {
  user(id: ID!): User
  posts(authorId: ID!, last: Int): [Post!]!
}

클라이언트는 이 스키마를 보고 어떤 데이터를 어떤 형태로 요청할 수 있는지 정확히 알 수 있다. 자동완성, 타입 검증, 문서화가 스키마 하나로 해결된다.

Mutation과 Subscription

GraphQL 작업은 세 가지 타입이 있다.

Query: 데이터 조회 (REST의 GET에 해당)
Mutation: 데이터 변경 (POST/PUT/DELETE에 해당)
Subscription: 실시간 구독. websocket 기반으로 서버 이벤트를 스트리밍 수신

Subscription은 AI 스트리밍 응답처럼 실시간 데이터가 필요한 상황에서 활용된다.

예시

AI 서비스에서 GraphQL을 활용하는 실제 쿼리 패턴:

# 특정 AI 모델의 상세 정보 + 최근 사용 이력 조회
query GetModelDetails {
  aiModel(slug: "claude-sonnet-4-6") {
    name
    provider
    contextWindow
    pricing {
      inputPer1kTokens
      outputPer1kTokens
    }
    recentBenchmarks(limit: 5) {
      name
      score
      measuredAt
    }
  }
}

# 새 AI 요청 뮤테이션
mutation CreateCompletion {
  createCompletion(input: {
    model: "claude-sonnet-4-6"
    prompt: "GraphQL을 한 문장으로 설명해줘"
    maxTokens: 200
  }) {
    id
    text
    tokenCount
    createdAt
  }
}

JavaScript/TypeScript에서 GraphQL 요청:

const response = await fetch('/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: `query { user(id: "123") { name avatarUrl } }`
  })
});
const { data } = await response.json();

활용 사례

GitHub API v4: GitHub은 REST API v3에서 GraphQL API v4로 전환. 단일 쿼리로 레포지토리·이슈·PR 데이터를 원하는 형태로 조회
Shopify: 이커머스 데이터(상품·주문·고객)를 GraphQL로 제공. 프론트엔드 팀이 필요한 필드만 선택해 성능 최적화
AI 서비스 데이터 계층: AI 플랫폼에서 모델 메타데이터, 사용 이력, 과금 데이터를 통합 조회할 때 GraphQL로 유연한 인터페이스 제공
모바일 앱: 네트워크 비용이 중요한 모바일 환경에서 불필요한 데이터 수신(Over-fetching) 최소화
BFF(Backend for Frontend): 여러 마이크로서비스 데이터를 GraphQL로 집계해 프론트엔드에 최적화된 응답 제공