REST API와 GraphQL

API란

API(Application Programming Interface)는

클라이언트(프론트엔드)와 서버(백엔드)가 데이터를 주고받는 약속이다.

데이터를 어떻게 요청하고, 어떤 형태로 받을 것인지를 정의하는 규칙이며,

이 약속의 구조는 REST와 GraphQL로 나뉜다.

REST API

REST(Representational State Transfer)는 2000년대 초부터 웹의 표준으로 자리잡았다. 자원(Resource) 중심의 설계된 구조.

특징

각 자원은 고유한 URL로 표현된다.

HTTP 메서드(GET, POST, …)로 동작을 구분하며, 동작은 다음과 같다.

• 조회(GET)
• 생성(POST)
• 수정(PUT/PATCH)
• 삭제(DELETE)

REST는 직관적이고 단순하며, URL을 보면 무슨 동작을 하는지 한눈에 파악하기 쉽다.

GraphQL

GraphQL은 2015년 Facebook이 만든 쿼리 언어로,

REST가 엔드포인트 중심이라면- GraphQL은 요청 데이터 중심이다.

query {
  user(id: 1) {
    name
    email
    posts(limit: 2) {
      title
      likes
    }
  }
}

이 한 줄의 쿼리로 사용자 정보와 게시글까지 한 번에 가져올 수 있다.

특징

• 단일 엔드포인트(/graphql)
• 필요한 데이터만 요청(over-fetching 방지)
• 하나의 요청으로 여러 리소스 결합(under-fetching 해결)

Over-Fetching / Under-Fetching 두 문제를 모두 해결할 수 있는 GraphQL

기존 REST는 데이터가 과하게 오거나 부족하게 오는 상황이 잦다는 한계점을 갖고 있다. 이를 해결하려면 별도의 API 엔드포인트를 새로 만들어야 했다.

GraphQL을 통해 필요한 필드만 선택적으로 요청, 따라서 네트워크의 효율을 향상시킬 수 있고 여러 리소스를 한 번의 요청으로 결합할 수 있게 되었다.

# REST에서는 두 번 요청해야 하는 걸 한 번에 처리
query {
  user(id: 1) {
    name
    posts {
      title
    }
  }
}

응답 구조 비교

GraphQL은 클라이언트가 요청한 필드만 정확히 반환한다.

REST

{
  "id": 1,
  "name": "Jihyun",
  "email": "jihyun@example.com",
  "phone": "010-1234-5678"
}

GraphQL

{
  "data": {
    "user": {
      "name": "Jihyun"
    }
  }
}

캐싱과 네트워크 효율성에서

REST

• HTTP의 기본 캐싱(ETag, Cache-Control)을 활용하기 쉬움.
• URL이 명확하므로 브라우저 캐시, CDN 캐시에도 유리.

GraphQL

• 요청이 POST 기반이라 캐싱이 어렵다.
• 캐시는 대부분 클라이언트 단에서 수동 관리 (예: Apollo Client, Relay).
• 대신 GraphQL은 부분 업데이트(Partial Cache Update)가 가능해, 세밀한 캐시 제어엔 오히려 강점을 가진다.

에러 처리 및 타입 안정성에서는?

REST

• 주로 HTTP 상태 코드(200, 404, 500) 기반.
• 단순하지만 세밀한 에러 구분이 어려움.

GraphQL

• 응답 본문에 errors 필드가 포함되어, 부분 성공/부분 실패를 명확히 표현 가능.
• 스키마 기반(Type System)이라 컴파일 타임에서 타입 검증 가능.

언제나 GraphQL 사용이 좋은걸까?

API 안정성이 중요하거나, 단순 CRUD 환경에에서는 REST가 효율과 편리성을 더 갖춘 선택지가 된다.

단, 모바일 환경이나 대화형 데이터, 복잡한 UI를 요하는 환경에서는 GraphQL을 사용하는 것이 적합하다.

항목	REST	GraphQL
설계 철학	자원(Resource) 중심	데이터(Query) 중심
엔드포인트	여러 개	단일 /graphql
요청 데이터 제어	서버 결정	클라이언트 결정
캐싱	브라우저/CDN 친화적	수동 관리 필요
요청 효율성	Over/Under-fetch 가능성 있음	필요한 데이터만 정확히
복잡한 관계 데이터	별도 엔드포인트 필요	한 쿼리로 결합 가능
학습 난이도	낮음	중간 이상

즉, 실무적으로는 REST, GraphQL 을 적절한 상황에 맞게 혼용해서 사용한다.

예를 들어, REST를 기본 API로 사용하되 GraphQL을 고정되지 않은 데이터 요청(대시보드, 검색 결과, 필터)용으로 사용하는 식이다.

→ GraphQL은 빠른 UI 반응성과 유연한 데이터 조합이 필요할 때 사용하면 된다.