BACKEND

GraphQL vs REST API 선택 가이드 — 캐싱·오류·보안 (2026)

junetapa 2026. 10. 29 업데이트 13 min read

GraphQL과 REST API 중 무엇을 고를지는 «어느 쪽이 더 새롭나»가 아니라 «응답 모양을 누가 정하고, 캐시·오류·보안을 어디서 처리하나»로 갈린다. 이 글은 두 방식의 차이를 그 네 갈래로 나눠 보고, 흔히 퍼진 오해(GraphQL은 항상 200, GraphQL은 캐시가 안 된다)를 공식 문서로 바로잡은 뒤, 프로젝트별 선택 기준과 함께 쓰는 구성을 정리한다. 사양과 권고는 2026년 10월 29일 graphql.org·GraphQL over HTTP 초안·OpenAPI 사양 페이지에서 다시 확인했다.

2026년 10월 다시 씀

예전 판의 «REST 사용 80% 이상·GraphQL 28%·엔터프라이즈 도입 340% 증가», 특정 라우터의 점유율, «gRPC가 사실상 표준» 같은 문장은 출처를 다시 확인할 수 없어 뺐다. «GraphQL은 항상 200을 돌려준다», «GraphQL은 모든 요청이 POST»라고 적었던 비교표 줄은 GraphQL over HTTP 작업 초안과 graphql.org 문서에 맞춰 고쳤다. «여러 번 봤다» 같은 확인할 수 없는 경험담도 뺐다.

핵심 차이 — 응답 모양을 누가 정하나

REST는 자원(resource) 중심이다. 주소가 곧 자원이고, GET /users/123은 123번 사용자를, DELETE /users/123은 그 사용자를 지운다. 응답에 어떤 필드가 들어갈지는 서버가 정한다. 그래서 화면 하나를 그리는 데 필요한 것보다 많이 받거나(over-fetching), 모자라서 다른 주소를 더 부르는(under-fetching) 일이 생긴다.

GraphQL은 스키마(타입 정의) 위에서 클라이언트가 필요한 필드를 직접 적어 보내는 쿼리 언어다. 보통 엔드포인트는 하나(/graphql)이고, «사용자 이름과 최근 글 세 개의 제목»처럼 응답 모양을 클라이언트가 정한다. 대신 그 자유 때문에 서버는 «어떤 쿼리가 올지 모른다»는 전제로 비용과 보안을 관리해야 한다.

같은 화면, 두 방식
# REST — 두 번 부르고, 필요 없는 필드도 받음
GET /api/users/123
GET /api/users/123/posts?limit=3

# GraphQL — 한 번에 필요한 필드만
query {
  user(id: "123") {
    name
    posts(first: 3) { title }
  }
}
리소스 중심의 레스트와 쿼리 중심의 그래프큐엘을 나눠 비교한 도해
서버가 응답 모양을 정하느냐, 클라이언트가 정하느냐.

REST 쪽 계약은 보통 OpenAPI 문서로 적는다. 2026년 10월 29일 확인한 OpenAPI 사양 최신판은 2026년 9월 10일의 3.2.1이다. OpenAPI 문서에서 클라이언트 타입을 만들어 쓰면, GraphQL 스키마가 주는 «응답 모양이 미리 정해진다»는 이점을 REST에서도 상당 부분 얻는다.

한눈에 보는 비교표

항목REST APIGraphQL
응답 모양서버가 주소마다 정함클라이언트가 쿼리로 정함(스키마 안에서)
계약 문서OpenAPI(따로 작성하거나 코드에서 생성)스키마 자체 · 인트로스펙션으로 조회
HTTP 메서드GET·POST·PUT·PATCH·DELETE로 행위 구분POST는 필수 지원, GET은 선택 지원(쿼리만 · 변경 작업 금지)
상태 코드자원·행위 결과를 상태 코드로요청 자체 오류는 4xx(초안) · 실행 중 일부 필드 오류는 200 + errors
HTTP 캐시주소 단위로 CDN·브라우저 캐시 쓰기 쉬움GET 쿼리 + 캐시 헤더로 가능 · 클라이언트 캐시는 전역 고유 id에 기댐
과한 요청 막기주소별 속도 제한깊이·너비·배치 제한, 비용 분석, 신뢰 문서
관측주소 패턴별로 응답 시간 추적단일 주소라 operation 이름별 계측을 따로 둠
판 관리/v1·/v2 또는 헤더필드 추가와 deprecated 표시로 스키마를 바꿔 감
파일 업로드multipart/form-data 그대로사양 밖 · 보통 별도 REST 주소나 미리 서명된 주소로

표에서 보듯 «무엇이 더 빠른가»보다 «어디서 무엇을 관리하나»의 차이가 크다. REST는 HTTP가 이미 가진 장치(메서드·상태 코드·캐시)를 그대로 쓰고, GraphQL은 그 장치 일부를 쿼리 층에서 다시 만든다.

오류와 상태 코드 — «항상 200»은 옛 관행

«GraphQL은 오류가 나도 200»이라는 말은 많은 서버가 예전에 그렇게 동작했기 때문에 퍼졌다. GraphQL 재단이 만드는 GraphQL over HTTP 사양(2026년 10월 29일 확인 기준 «현재 작업 초안»)은 이를 나눠서 정한다.

  • 응답 미디어 타입 — 서버는 application/graphql-response+json을 지원해야 하고, 클라이언트는 Accept 헤더에 이 타입을 넣는다. application/json만 보내는 예전 클라이언트에는 2xx 응답을 그 타입으로 준다.
  • 요청 자체가 틀렸을 때 — 문서를 해석하지 못하거나 검증에 실패해 data가 없으면 4xx·5xx를 돌려야 한다. 예로 해석 실패 400, 검증 실패 422를 든다.
  • 실행 중 일부 필드만 실패 — data가 있으면 2xx이고, 필드 오류만 있는 경우는 200을 권한다. data와 errors가 함께 있으면 «부분 성공»을 뜻하는 294를 쓰도록 권한다.
  • 판단 기준 — 클라이언트는 상태 코드와 상관없이 application/graphql-response+json 본문의 data·errors로 결과를 판단하라고 적는다.

정리하면, GraphQL에서도 «요청이 잘못됐다»는 상태 코드로 알 수 있게 바뀌는 중이고, «일부만 실패»는 여전히 본문을 봐야 한다. 모니터링에서 5xx 비율만 보고 GraphQL 서버의 오류율을 판단하면 필드 오류를 놓친다는 점은 그대로다. REST 쪽에서 오류 본문 모양을 맞추는 방법(RFC 9457)은 Go REST API 서버 구축의 오류 응답 절에 예제와 함께 정리했다.

캐싱 — GET과 persisted query

REST의 큰 장점은 주소가 곧 캐시 키라는 점이다. graphql.org 캐싱 문서도 «엔드포인트 기반 API에서는 주소가 전역 고유 식별자라 클라이언트가 캐시를 만들 수 있지만, GraphQL에는 그런 주소 같은 기본 단위가 없다»고 적는다. 그래서 GraphQL에서는 두 가지를 따로 챙긴다.

클라이언트 캐시 — 전역 고유 id

graphql.org는 id 같은 필드를 전역 고유 식별자로 예약해 두는 패턴을 권한다. 백엔드에 전역 고유 id가 없다면 타입 이름을 붙여 만들고 base64로 감추는 방법, 또는 클라이언트가 __typename과 id를 합쳐 쓰는 방법을 든다. 클라이언트 라이브러리의 정규화 캐시가 이 id에 기대어 같은 객체를 한 번만 저장한다.

HTTP 캐시 — GET 쿼리와 persisted query

graphql.org 성능 문서는 쿼리를 GET으로 보내면 보통 캐시 가능한 요청으로 취급돼, 응답에 캐시 헤더를 주면 CDN을 쓸 수 있다고 설명한다. 문제는 주소 길이다. 브라우저와 CDN이 주소 길이를 제한하므로 큰 쿼리는 쿼리 문자열에 다 담기 어렵다. 이때 persisted query(신뢰 문서 또는 자동 persisted query)를 쓰면 클라이언트는 쿼리 대신 해시만 보내고, 서버는 저장소에서 해시로 원문을 찾는다. GraphQL over HTTP 초안은 변경 작업(mutation)을 GET으로 실행하지 못하게 하고, 그런 요청에는 4xx(권장 405)를 돌려주도록 정했다.

네트워크 성능과 캐싱, 모니터링에서 두 방식의 차이를 정리한 도해
운영에 들어가면 성능보다 «캐싱과 관측»에서 차이가 크다.

읽기 비중이 높고 같은 응답을 많은 사용자가 받는 콘텐츠 서비스라면, REST의 주소 단위 캐시가 여전히 가장 단순한 길이다. GraphQL로도 같은 효과를 낼 수 있지만 GET 전환, 해시 저장소, 캐시 헤더 설계라는 일이 더 붙는다.

보안 — 깊이·비용 제한과 신뢰 문서

REST에서는 주소마다 하는 일이 정해져 있어 «이 주소는 분당 몇 번»으로 막으면 된다. GraphQL은 한 요청이 얼마나 비쌀지 실행 전에는 알 수 없다. graphql.org 보안 문서가 권하는 장치는 층층이 쌓는 방식이다.

장치막는 것graphql.org 권고 요지
깊이 제한friends { friends { friends … } } } 같은 깊은 중첩실행 전에 필드 깊이 상한으로 거절 · 목록 중첩은 더 작은 상한
너비·배치 제한별칭으로 같은 필드를 수십 번 부르기, 한 번에 많은 쿼리 묶기최상위 필드·별칭 수, 배치 안 쿼리 수에 상한
복잡도(비용) 분석얕지만 비싼 필드 조합타입·필드에 가중치를 주고 요청당 최대 비용을 넘으면 거절 · 비용을 속도 제한 예산에서 차감
속도 제한비싼 필드의 반복 호출네트워크 층보다 비즈니스 로직 층에서
신뢰 문서미리 알 수 없는 임의 쿼리 전부허용 목록의 문서 id만 실행 · 자사 클라이언트용(공개 API에는 못 씀)
인트로스펙션 끄기스키마 훑어보기자사 클라이언트만 쓰면 운영 환경에서 막을 수 있으나 그것만으로는 부족(오류 메시지로도 추측 가능)

graphql.org는 인트로스펙션을 끄거나 오류를 감추는 것보다 문서 허용 목록(신뢰 문서)이 더 효과적이라고 정리한다. 웹·앱처럼 쿼리를 자기 팀이 다 쓰는 구조라면 처음부터 신뢰 문서를 기본으로 두고, 외부 개발자에게 여는 공개 GraphQL API라면 깊이·너비·비용 제한과 속도 제한을 함께 쓰는 것이 출발점이다.

N+1 문제와 DataLoader

GraphQL은 필드마다 리졸버(값을 가져오는 함수)가 따로 돈다. 사용자 목록 100명을 가져온 뒤 각자의 글을 부르면, 목록 쿼리 1번에 사용자마다 1번씩 해서 101번이 나간다. graphql.org 성능 문서는 이를 «첫 요청이 N개의 뒤따르는 요청을 부르는» N+1 문제로 설명하고, 짧은 시간 동안 모인 요청을 묶어 한 번에 보내는 배칭을 해법으로 든다. 그 대표 도구가 DataLoader다.

DataLoader로 묶기 (JavaScript)
import DataLoader from 'dataloader';

// 요청마다 새로 만듦 (사용자 간 캐시 섞임 방지)
const postsByUser = new DataLoader(async (userIds) => {
  const rows = await db.posts.findMany({ where: { userId: { in: userIds } } });
  // 입력 순서대로 결과 배열을 돌려줘야 함
  return userIds.map((id) => rows.filter((p) => p.userId === id));
});

const resolvers = {
  User: {
    posts: (user) => postsByUser.load(user.id), // 100번 호출 → DB 1번
  },
};

N+1은 REST에도 있다. 다만 REST는 서버가 응답 모양을 정하므로 개발자가 쿼리를 미리 최적화해 두면 끝나지만, GraphQL은 클라이언트가 관계를 자유롭게 따라가므로 어떤 조합이 올지 모른다. 그래서 관계 필드에는 처음부터 배칭을 기본으로 둔다. 목록 필드에는 페이지 나누기(first·커서)를 두는 것도 graphql.org가 과한 요청을 막는 장치로 함께 든다.

고르는 기준과 함께 쓰는 구성

팀 규모와 클라이언트 종류에 따른 선택 기준을 정리한 도해
팀이 작고 클라이언트가 하나면 REST 로 충분한 경우가 많다.
상황먼저 볼 선택이유
외부 개발자에게 여는 공개 APIREST + OpenAPI익숙한 HTTP 의미, 주소 단위 캐시·속도 제한, 신뢰 문서를 못 쓰는 공개 GraphQL의 보안 부담 회피
웹·앱 등 클라이언트가 여럿이고 화면마다 필요한 데이터가 다름GraphQL(BFF 층)화면마다 필요한 필드만, 스키마가 프런트·백엔드 계약
읽기 위주 콘텐츠, CDN 캐시가 비용을 좌우REST주소가 곧 캐시 키
프런트·백엔드 모두 TypeScript, 외부 공개 없음tRPC도 후보스키마·코드 생성 없이 타입 추론으로 끝에서 끝까지 타입 일치(공식 소개 · 현재 11.x)
내부 서비스끼리 호출REST 또는 gRPCgRPC는 브라우저에서 바로 부르려면 gRPC-Web과 Envoy 같은 프록시를 둠(공식 예제)

한 서비스에 하나만 고를 필요는 없다. 흔한 구성은 외부 공개 API는 REST, 자사 웹·앱이 쓰는 층은 GraphQL로 나누고, GraphQL 서버는 내부 REST 서비스들을 불러 모으는 BFF 역할을 맡기는 것이다. 이렇게 하면 공개 API는 HTTP 캐시와 단순한 속도 제한을 그대로 쓰고, 자사 클라이언트용 GraphQL에는 신뢰 문서를 걸 수 있다. 서버 쪽 언어를 고르는 중이라면 FastAPI vs Django vs Flask 선택 가이드가, TypeScript로 타입 계약을 다루는 방법은 TypeScript 5 실무 필수 패턴 총정리가 이어서 읽기 좋다.

REST에서 GraphQL로 옮길 때

이미 돌아가는 REST API를 한 번에 GraphQL로 바꾸면 클라이언트·서버·운영 도구가 동시에 바뀐다. 기존 REST를 그대로 두고 그 위에 GraphQL 층을 얹어 화면 단위로 옮기는 편이 위험이 작다.

01

한 화면부터

데이터를 여러 주소에서 모아 그리는 화면 하나를 골라, 그 화면용 쿼리만 GraphQL로 만든다. 리졸버는 기존 REST 주소를 부른다.

02

보안·성능 장치를 첫날부터

깊이·비용 제한, 관계 필드 배칭, operation 이름별 계측을 처음 배포에 같이 넣는다. 나중에 붙이면 이미 쓰이는 쿼리를 깨뜨릴 수 있다.

03

스키마는 지우지 말고 표시

필드를 바꿀 때는 새 필드를 더하고 옛 필드에 deprecated 표시를 단 뒤, 쓰는 클라이언트가 없어진 것을 확인하고 뺀다.

자주 묻는 것

GraphQL은 오류가 나도 항상 200을 돌려주나요?

예전 관행일 뿐 규칙은 아닙니다. GraphQL over HTTP 작업 초안은 문서를 해석하지 못하거나 검증에 실패해 data가 없으면 400·422 같은 4xx나 5xx를 돌려야 한다고 적습니다. 실행 중 일부 필드만 실패하면 200을 권하고, 결과는 상태 코드와 상관없이 응답 본문으로 판단하라고 안내합니다.

GraphQL도 HTTP 캐시와 CDN을 쓸 수 있나요?

쓸 수 있습니다. graphql.org 성능 문서는 쿼리를 GET으로 보내면 보통 캐시 가능한 요청으로 취급돼 캐시 헤더와 함께 CDN을 쓸 수 있다고 설명합니다. 주소 길이 한도 때문에 큰 쿼리는 해시만 보내는 persisted query와 함께 쓰는 경우가 많습니다. 변경 작업(mutation)은 GET으로 실행하면 안 됩니다.

GraphQL API를 열 때 가장 먼저 막아야 할 것은 무엇인가요?

지나치게 깊거나 넓은 쿼리입니다. graphql.org 보안 문서는 필드 깊이 제한, 최상위 필드·별칭·배치 수 제한, 필드 가중치로 비용을 셈하는 복잡도 분석, 비즈니스 로직 층의 속도 제한을 권하고, 자사 클라이언트만 쓰는 API라면 허용된 문서만 실행하는 신뢰 문서(trusted documents)가 더 효과적이라고 적습니다.

프런트와 백엔드가 모두 TypeScript면 무엇을 고르나요?

외부에 공개하지 않는 API라면 tRPC도 후보입니다. tRPC는 스키마나 코드 생성 없이 TypeScript 타입 추론으로 끝에서 끝까지 타입이 맞는 API를 만든다고 소개합니다. 다른 언어 클라이언트나 외부 개발자가 쓰는 API라면 OpenAPI로 계약을 적는 REST나 스키마가 있는 GraphQL이 맞습니다.

정리

GraphQL vs REST API의 선택은 «응답 모양을 누가 정하나»에서 시작한다. 서버가 정하는 REST는 HTTP의 메서드·상태 코드·캐시를 그대로 쓰고, 클라이언트가 정하는 GraphQL은 그 자유의 대가로 깊이·비용 제한, 배칭, 별도 캐시 설계를 서버가 떠안는다. «GraphQL은 항상 200», «GraphQL은 캐시가 안 된다»는 말은 이제 반쯤만 맞다. 공개 API는 REST, 자사 클라이언트용 층은 GraphQL처럼 층마다 나눠 쓰는 구성이 두 방식의 장점을 함께 가져가는 가장 흔한 답이다.

GraphQL vs REST API 선택 가이드 대표 그림 — 왼쪽에 제목과 «GET 캐시 · N+1 배칭» 배지가 있고, 오른쪽에 색이 다른 우편함 네 개(여러 주소)에서 나온 화살표가 번개·방패가 달린 구름(캐시·보안)을 거쳐 여러 점이 이어진 육각형 허브(하나의 그래프)로 모이는 장면
GraphQL vs REST API 선택 가이드 — 캐싱·오류·보안 (2026).

참고 자료

  1. GraphQL over HTTP — Current Working Draft: POST 필수·GET 선택, GET으로 mutation 금지(4xx·405 권장), application/graphql-response+json, 400·422·200·294 상태 코드 규칙(2026-10-29 확인). graphql.github.io
  2. graphql.org. Security — 깊이·너비·배치 제한, 복잡도 분석, 속도 제한, 신뢰 문서, 인트로스펙션(2026-10-29 확인). graphql.org
  3. graphql.org. Performance — N+1과 DataLoader 배칭, GET과 HTTP 캐시·CDN, 주소 길이 한도, persisted query(2026-10-29 확인). graphql.org
  4. graphql.org. Caching — 주소 = 전역 고유 식별자, 전역 고유 id 패턴, __typename 조합(2026-10-29 확인). graphql.org
  5. OpenAPI Initiative. OpenAPI Specification — 최신 3.2.1, 2026-09-10(2026-10-29 확인). spec.openapis.org
  6. tRPC Docs — «스키마나 코드 생성 없이» 타입 안전 API, 현재 11.x(2026-10-29 확인). trpc.io
  7. gRPC. gRPC-Web Basics — 브라우저 요청을 Envoy 프록시로 gRPC 서버에 넘기는 예(2026-10-29 확인). grpc.io
GraphQL REST API API 설계 OpenAPI GraphQL 보안 DataLoader tRPC 백엔드
junetapa(박준철)
개발자가 아니라 쓰는 사람. IT 현장 27년의 기준으로 AI 도구를 고르고 기록한다.
Twitter Facebook URL 복사