REST API vs GraphQL API의 데이터 통합 관점 차이

Seongyong's PLOG·2025년 10월 9일

목록 보기

2/2

1. 서론

REST와 GraphQL은 모두 널리 쓰이는 API 접근 방식이지만, 데이터를 어떻게 요청·조합·전달할 것인지에 대한 철학이 다르다. 본 글은 두 방식을 데이터 통합 관점에서 비교하고, 어떤 상황에서 어떤 방식을 선택할지 실무 기준을 제시한다.

2. 개념적 차이

항목	REST API	GraphQL API
기본 개념	자원(Resource) 중심	질의(Query) 중심
엔드포인트	다수(`/users`, `/orders`)	단일(`/graphql`)
응답 구조	서버가 고정 정의	클라이언트가 선택(필드 단위)
문서화	Swagger/OpenAPI	스키마 자체가 문서화(Self-documenting)
변경 관리	버전 분기(`/v1`, `/v2`)	스키마 확장/Deprecated 필드

3. 요청/응답 구조 비교

3.1 REST 방식(예시)

두 서비스가 있다고 가정한다. User는 사용자 서비스, Attendance는 이벤트 서비스가 소유.

GET /users/1
→ { "id": 1, "name": "Kim", "email": "kim@example.com" }

GET /attendance?userId=1
→ { "userId": 1, "streak": 6, "lastAttendanceDate": "2025-10-08" }

클라이언트는 두 번 호출하고 결과를 합쳐 화면을 만든다.
필요 이상 데이터를 포함하거나(Overfetching), 원하는 데이터를 얻기 위해 여러 번 호출(Underfetching)할 수 있다.

3.2 GraphQL 방식(예시)

하나의 질의로 필요한 필드만 요청한다.

# POST /graphql
query {
  user(id: 1) {
    name
    attendance {
      streak
      lastAttendanceDate
    }
  }
}

응답:

{
  "data": {
    "user": {
      "name": "Kim",
      "attendance": {
        "streak": 6,
        "lastAttendanceDate": "2025-10-08"
      }
    }
  }
}

한 번의 요청으로 다수 서비스 데이터를 통합하여 수신.
필요한 필드만 골라 받아 Over/Underfetching 문제를 최소화.

4. Overfetching / Underfetching

REST: 엔드포인트별 고정 응답 구조 탓에, 과다 데이터 수신(Overfetching)이나 여러 API 호출(Underfetching)이 발생하기 쉽다.
GraphQL: 클라이언트가 필드를 선택해 요청하므로 두 문제를 구조적으로 완화한다.

5. 엔드포인트와 버전 관리

5.1 엔드포인트 구조

항목	REST	GraphQL
요청 방식	URL + 메서드	단일 URL + 질의 언어
응답 구조	서버가 정함	클라이언트가 선택

5.2 버전 관리

REST: /api/v1/users, /api/v2/users 처럼 URL 버전을 분리.
GraphQL: 필드 Deprecation을 활용해 점진적 변경을 유도.

type User {
  id: ID!
  name: String!
  email: String @deprecated(reason: "Use contact.email instead")
  contact: Contact
}

6. 데이터 통합: REST Aggregation vs GraphQL Federation

6.1 REST Aggregation(게이트웨이 집계)

Gateway가 여러 REST 서비스를 호출해 응답을 합쳐 단일 응답으로 제공할 수 있다.

// 예시: GET /api/user/summary/:id
// 사용자 기본 정보 + 출석 정보를 합쳐 반환
const user = await http.get(`http://user-service/users/${id}`);
const attendance = await http.get(`http://event-service/attendance?userId=${id}`);
return {
  id,
  name: user.data.name,
  attendance: {
    streak: attendance.data.streak,
    lastDate: attendance.data.lastAttendanceDate,
  },
};

장점: 단순하고 의도 통제가 쉬움.
단점: 통합 포인트가 늘수록 엔드포인트 폭증, 응답 구조 중복, 문서 동기화 부담.

6.2 GraphQL Federation(스키마 기반 통합)

여러 서비스의 스키마를 합쳐 하나의 GraphQL 게이트웨이가 질의를 분해/중계/집계한다.

클라이언트는 단일 /graphql로 다양한 조합을 자유롭게 질의.
응답 구조는 스키마로 일원화되고, 필드 단위로 점진적 변경이 가능.

장점: 클라이언트 주도형 통합, 스키마 일관성, Over/Underfetching 완화.
단점: Federation 구성 복잡성, N+1·캐싱·관측성 설계 필요, 운영 난이도.

핵심 정리

REST도 “게이트웨이에서 합치면” 데이터 통합이 가능하다.
GraphQL은 그 과정을 스키마와 질의 언어로 표준화하여, 통합 지점을 코드가 아닌 스키마 레벨에서 관리하도록 해준다.

7. 단점과 주의사항

항목	REST	GraphQL
장점	단순, 캐싱 용이, 관측 쉬움	유연한 질의, 통합 조회, 스키마 문서화
단점	다중 요청·엔드포인트 폭증	복잡한 쿼리로 서버 부하, 캐싱/관측 난이도
성숙도	매우 높음	빠르게 성장 중이나 운영 난이도 존재
적합	행위 중심(로그인/명령형), 단순 API	조회 중심 복합 화면, 집계/탐색형 API

8. 선택 가이드(실무 요약)

1) 행위 중심(CUD)·단순 트랜잭션: REST(또는 REST + MQ).
2) 조회 중심·복합 화면: GraphQL(또는 REST Aggregation).
3) 내부 대량 조회/저지연: gRPC(또는 GraphQL 서브그래프 내부 호출).
4) 상태 변경 전파/비동기 파이프라인: MQ(Kafka/RabbitMQ/Redis Streams).
5) 혼합 전략: /auth, /admin 등은 REST, 복합 조회는 /graphql로 제공.

9. 결론

REST와 GraphQL 모두 데이터 통합이 가능하다.
차이는 “어디에서, 어떤 추상화로 통합을 관리하느냐”에 있다.
- REST: 게이트웨이 코드로 엔드포인트별 통합 구현(명령적).
- GraphQL: 스키마·질의 언어로 통합을 선언/조합(선언적).
팀의 역량, 트래픽 특성, 화면 복잡도, 운영 도구 성숙도에 따라 병행 구성이 최선일 수 있다.

Seongyong's PLOG

성용의 프로그래밍 블로그

이전 포스트