들어가며: 우리가 사는 API의 시대 🌐

안녕! 👋 오늘 좀 딥(Deep)한 얘기를 나눠볼까 해. 바로 API에 대한 이야기야.
"API? 그거 개발자들이나 쓰는 거 아냐?" 라고 생각할 수도 있겠지. 맞아, 근데 사실 우린 매일 API의 세상 속에서 살고 있어.

스마트폰으로 날씨를 확인하고, 지도 앱으로 길을 찾고, 친구에게 메시지를 보내고, 온라인 쇼핑을 하는 그 모든 순간! 사실은 보이지 않는 곳에서 수많은 API들이 쉴 새 없이 데이터를 주고받으며 일하고 있는 덕분이야. 마치 식당에 가서 메뉴판을 보고 주문하면, 주방에서 요리가 나와 우리에게 전달되는 과정과 같아. 여기서 메뉴판과 웨이터 역할을 하는 게 바로 API(Application Programming Interface)지.

API는 애플리케이션(앱)과 서버, 또는 서비스와 서비스 사이의 '소통 규칙', 즉 인터페이스야. 이 규칙을 어떻게 정하느냐에 따라 개발의 효율성, 앱의 성능, 심지어는 비즈니스의 확장성까지 달라질 수 있어. 그만큼 중요하단 얘기!

그런데 이 '소통 규칙'을 만드는 데에는 크게 두 가지 방식이 있어. 오랫동안 웹의 제왕으로 군림해 온 'REST API'라는 방식과, 페이스북에서 모바일 시대를 위해 탄생시킨 무서운 신예 'GraphQL'이 바로 그 주인공들이야.

Chapter 1. 웹의 표준, 관록의 챔피언: REST API 👑

먼저 우리에게 아주 익숙한, 웹 개발의 '국룰'과도 같은 REST API에 대해 알아보자. REST는 'Representational State Transfer'의 약자인데, 이름부터 뭔가 좀 딱딱하고 어려워 보이지? 괜찮아, 핵심만 쏙쏙 뽑아서 알려줄게.

REST의 탄생과 철학: "웹은 원래 이렇게 쓰는 거야!"

REST는 2000년에 로이 필딩(Roy Fielding)이라는 분의 박사 논문에서 처음 등장했어. 이 분은 HTTP 프로토콜의 주요 설계자 중 한 명이기도 해. 즉, "내가 웹 통신의 근본인 HTTP를 만들어봤는데, 이걸 가장 잘 활용하는 아키텍처 스타일은 바로 이런 거야!"라고 제시한 게 바로 REST라고 할 수 있지.

REST의 핵심 철학은 '자원(Resource)'과 '행위(Verb)', 그리고 '표현(Representation)'으로 모든 것을 설명하는 거야.

* 자원(Resource): 우리가 다루는 모든 데이터. 예를 들어 '회원 정보', '게시글', '상품' 같은 것들이 모두 자원이야. 이 자원들은 각각 고유한 주소(URI)를 가져. `/users/123` 처럼 말이지. * 행위(Verb): 이 자원들을 어떻게 다룰 것인가? 이건 HTTP의 기본 메소드인 GET, POST, PUT, DELETE 등을 사용해서 표현해. '조회(GET)', '생성(POST)', '수정(PUT)', '삭제(DELETE)'처럼 직관적이지. * 표현(Representation): 자원을 어떤 형태로 주고받을 것인가? 보통은 JSON이나 XML 같은 데이터 포맷으로 주고받아.

이 세 가지를 조합하면 "`/users/123` 이라는 주소의 자원(회원 정보)을 GET(조회)해서 JSON 형태로 보여줘" 와 같은 명확한 요청이 만들어지는 거지. 아주 심플하고 직관적이지?

REST를 REST답게 만드는 6가지 원칙 (제약 조건)

로이 필딩은 REST 아키텍처를 따르려면 다음 6가지 제약 조건을 지켜야 한다고 말했어. 이게 좀 이론적이라 지루할 수 있지만, REST의 근본을 이해하려면 꼭 필요하니까 집중해봐!

1. 클라이언트-서버 (Client-Server)

이건 너무 당연한 얘기일 수 있는데, 사용자와 상호작용하는 클라이언트(웹 브라우저, 모바일 앱 등)와 데이터를 저장하고 처리하는 서버의 역할을 명확하게 분리해야 한다는 원칙이야. 이렇게 분리하면 서로 독립적으로 발전할 수 있어. 서버는 데이터 관리에만 집중하고, 클라이언트는 UI/UX에만 집중할 수 있게 되는 거지.

2. 무상태성 (Stateless)

이게 정말 중요한 개념이야. 서버는 클라이언트의 상태를 저장하지 않는다는 뜻이야. 각 요청은 그 자체로 완전한 정보를 담고 있어야 해. 서버는 이전 요청이 뭐였는지 전혀 기억하지 않아.

예를 들어, 자판기를 생각해보자. 내가 콜라를 뽑든, 사이다를 뽑든 자판기는 내가 이전에 뭘 뽑았는지 기억하지 않지? 매번 새로운 요청으로 처리할 뿐이야. 이게 바로 Stateless야. 덕분에 서버는 요청을 처리하는 데만 집중할 수 있어서 구조가 단순해지고, 서버를 여러 대로 늘리는 수평 확장(Scale-out)에도 매우 유리해져.

3. 캐시 가능 (Cacheable)

웹의 성능을 좌우하는 핵심 요소 중 하나가 바로 '캐시'야. REST는 HTTP의 캐싱 기능을 그대로 활용할 수 있어. 서버는 응답 데이터에 "이 데이터는 1시간 동안 캐시해도 돼" (`Cache-Control: max-age=3600`) 같은 정보를 담아서 보낼 수 있어. 클라이언트는 이 정보를 보고 동일한 요청을 다시 서버에 보내지 않고, 저장해둔 데이터를 재사용해서 속도를 비약적으로 높일 수 있지.

4. 균일한 인터페이스 (Uniform Interface)

이 원칙 덕분에 REST가 범용적으로 쓰일 수 있게 됐어. 클라이언트와 서버는 하나의 통일된 규칙으로 소통해야 한다는 거야. 세부적으로 4가지 하위 원칙이 있어.

• 자원의 식별 (Identification of resources): 모든 자원은 `/users/123` 같은 URI로 유일하게 식별되어야 해.
• 표현을 통한 자원 조작 (Manipulation of resources through representations): 클라이언트가 받은 JSON 데이터에는 자원을 수정하거나 삭제하는 데 충분한 정보가 담겨 있어야 해.
• 자기 서술적 메시지 (Self-descriptive messages): 각 메시지는 그 자체로 완전한 정보를 담고 있어야 해. 예를 들어, "이 메시지는 JSON 형식이야" (`Content-Type: application/json`) 같은 메타데이터를 포함해서, 메시지를 받는 쪽이 이걸 어떻게 처리해야 할지 명확히 알 수 있어야 한다는 거지.
• HATEOAS (Hypermedia as the Engine of Application State): 이름이 좀 무섭지? 😅 쉽게 말해, 서버의 응답에 다음에 할 수 있는 액션에 대한 링크를 포함시켜라는 거야. 예를 들어 `/users/123` 정보를 조회했을 때, 응답 데이터 안에 "이 유저의 게시글 목록 보기: `/users/123/posts`", "이 유저 정보 수정하기: `/users/123` (PUT 요청)" 같은 링크를 함께 제공하는 거지. 클라이언트는 이 링크를 따라가기만 하면 되니까, 서버의 API 구조가 바뀌어도 클라이언트 코드를 수정할 필요가 줄어들어. 하지만 현실에서는 HATEOAS를 완벽하게 지키는 경우는 드물어.

5. 계층화 시스템 (Layered System)

클라이언트와 서버 사이에 로드 밸런서, 프록시, 게이트웨이 같은 중간 서버들을 둘 수 있는 구조를 말해. 클라이언트는 최종 서버에 직접 연결되었는지, 중간 서버를 거치는지 알 필요가 없어. 이런 계층 구조 덕분에 보안 강화, 부하 분산, 암호화 등 다양한 기능을 추가하기가 쉬워져.

6. 주문형 코드 (Code-On-Demand, Optional)

이건 유일하게 선택적인 원칙이야. 서버가 클라이언트에 실행 가능한 코드(예: JavaScript)를 보내서, 클라이언트의 기능을 일시적으로 확장할 수 있다는 개념이야. 우리가 웹사이트에 접속하면 브라우저가 JavaScript를 내려받아 실행하는 걸 생각하면 돼.

그래서 REST는 어떻게 쓰는데? (실전 예제)

백문이 불여일견! 실제 게시판 API를 만든다고 상상해보자.

자원 정의

• 게시글 목록: `/posts`
• 특정 게시글: `/posts/{postId}`
• 특정 게시글의 댓글 목록: `/posts/{postId}/comments`
• 특정 댓글: `/posts/{postId}/comments/{commentId}`

HTTP 메소드 활용

1. 모든 게시글 조회하기 (GET)

클라이언트는 서버에 이런 요청을 보내.

GET /posts HTTP/1.1
Host: api.example.com

서버는 성공했다면 `200 OK` 상태 코드와 함께 게시글 목록을 JSON으로 응답해.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "title": "REST API는 정말 최고야!",
    "author": "김개발",
    "createdAt": "2023-10-27T10:00:00Z"
  },
  {
    "id": 2,
    "title": "GraphQL도 궁금한데?",
    "author": "이코딩",
    "createdAt": "2023-10-27T11:00:00Z"
  }
]

2. 새로운 게시글 작성하기 (POST)

클라이언트는 작성할 게시글 정보를 `body`에 담아 보내.

POST /posts HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "title": "새로운 글을 써봅니다",
  "content": "내용은 여기에...",
  "author": "박주니어"
}

서버는 게시글을 성공적으로 생성했다면 `201 Created` 상태 코드와 함께 생성된 자원의 주소(`Location` 헤더)와 정보를 응답해.

HTTP/1.1 201 Created
Location: /posts/3
Content-Type: application/json

{
  "id": 3,
  "title": "새로운 글을 써봅니다",
  "content": "내용은 여기에...",
  "author": "박주니어",
  "createdAt": "2023-10-27T12:00:00Z"
}

3. 특정 게시글 수정하기 (PUT)

1번 게시글의 전체 내용을 수정하고 싶다면?

PUT /posts/1 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "title": "REST API는 정말 최고야! (수정됨)",
  "content": "내용도 수정했어요."
}

서버는 성공적으로 수정했다면 `200 OK`와 함께 수정된 자원 정보를 응답해. (참고: `PUT`은 전체 교체, `PATCH`는 부분 수정을 의미하는데, 실무에서는 `PUT`으로 부분 수정까지 처리하는 경우도 많아.)

4. 특정 게시글 삭제하기 (DELETE)

2번 게시글을 삭제하고 싶다면?

DELETE /posts/2 HTTP/1.1
Host: api.example.com

서버는 성공적으로 삭제했다면 `204 No Content` 상태 코드를 응답해. 본문(body)은 비어있지.

REST의 빛과 그림자 ☀️🌑

이렇게 잘 만들어진 REST는 오랫동안 웹 API의 표준으로 자리 잡았어. 하지만 세상에 완벽한 기술은 없지. REST에도 명확한 장점과 한계가 존재해.

👍 REST의 장점 (빛)

• 단순함과 명확함: HTTP를 아는 사람이라면 누구나 쉽게 이해하고 사용할 수 있어. 러닝 커브가 낮지.
• 성숙한 생태계: 수많은 개발 도구, 라이브러리, 프레임워크, 그리고 방대한 레퍼런스가 존재해. 막히는 부분이 있어도 구글링하면 대부분 해결돼.
• HTTP 표준 활용: 캐싱, 인증, 상태 코드 등 검증된 웹 표준을 그대로 활용하므로 안정성과 확장성이 뛰어나.
• 플랫폼 독립성: 특정 언어나 기술에 종속되지 않아. JSON, XML 등 다양한 데이터 포맷을 지원하며, 어떤 클라이언트와도 통신할 수 있어.

👎 REST의 단점 (그림자)

시대가 변하면서, 특히 모바일 앱과 복잡한 웹 애플리케이션이 대세가 되면서 REST의 단점들이 부각되기 시작했어. 이게 바로 GraphQL이 등장하게 된 배경이야.

• 오버페칭 (Over-fetching): 필요한 것보다 더 많은 데이터를 받는 문제. 예를 들어, 게시글 목록 화면에서는 각 게시글의 '제목'과 '작성자'만 필요한데, `GET /posts` API는 게시글의 '내용', '생성일', '수정일' 등 모든 정보를 다 보내주는 거야. 이건 특히 데이터 사용량이 중요한 모바일 환경에서 큰 낭비지.
• 언더페칭 (Under-fetching): 하나의 화면을 구성하기 위해 여러 번의 요청을 보내야 하는 문제. 예를 들어, 유저 프로필 화면을 만드는데 유저 정보(`GET /users/123`), 그 유저가 쓴 글 목록(`GET /users/123/posts`), 그리고 그 유저의 친구 목록(`GET /users/123/friends`)이 필요하다고 해보자. 클라이언트는 총 3번의 API 요청을 보내야 해. 네트워크 요청이 많아질수록 화면 로딩 속도는 느려질 수밖에 없어. 이걸 N+1 문제라고도 불러.
• 경직된 데이터 구조: API의 응답 데이터 구조는 전적으로 서버가 결정해. 클라이언트는 그냥 주는 대로 받아야 하지. 만약 클라이언트에서 새로운 필드가 필요해지면, 백엔드 개발자에게 요청해서 API를 수정하고 배포해야만 해. 프론트엔드와 백엔드 개발 사이의 의존성이 높아지는 거야.
• 버전 관리의 어려움: API에 큰 변화가 생기면 기존 클라이언트와의 호환성을 위해 버전을 관리해야 해. `/v1/posts`, `/v2/posts` 처럼 URI에 버전을 넣는 방식이 일반적인데, 버전이 늘어날수록 관리 포인트가 늘어나고 복잡해져.

Chapter 2. 필요한 데이터만 쏙! 맞춤형 해결사: GraphQL 🤖

자, 이제 새로운 도전자 GraphQL에 대해 알아볼 시간이야. GraphQL은 'Graph Query Language'의 약자야. 이름에 'Query Language'가 들어가서 데이터베이스 언어(SQL 같은)로 오해할 수 있지만, GraphQL은 API를 위한 쿼리 언어이자 서버사이드 런타임이야.

GraphQL의 탄생: "모바일 퍼스트 시대의 고민"

GraphQL은 2012년 페이스북 내부에서 시작됐어. 당시 페이스북은 모바일 앱으로의 전환을 가속화하고 있었는데, REST API 방식으로는 골치 아픈 문제들이 많았지.

느린 네트워크 환경의 모바일 기기에서 REST API의 오버페칭/언더페칭 문제는 정말 치명적이었어. 뉴스피드 하나를 보여주기 위해 수십, 수백 개의 API를 호출해야 했고, 불필요한 데이터 때문에 로딩은 하염없이 길어졌지. 프론트엔드 개발자들은 화면에 작은 기능 하나 추가하려고 해도 매번 백엔드 팀에 API 수정을 요청해야 했어.

이런 문제를 해결하기 위해 페이스북은 완전히 새로운 접근법을 고안했어. "서버가 데이터 구조를 결정하는 게 아니라, 클라이언트가 필요한 데이터의 구조를 직접 요청하면 어떨까?" 이 발상의 전환이 바로 GraphQL의 시작이었어. 2015년에 오픈소스로 공개된 이후, GitHub, Airbnb, Netflix 등 수많은 빅테크 기업들이 채택하면서 빠르게 성장했지.

GraphQL의 핵심 컨셉: "네가 뭘 원하는지 말만 해!"

GraphQL은 REST와는 완전히 다른 방식으로 동작해. 몇 가지 핵심적인 특징을 살펴보자.

1. 스키마 (Schema) & 타입 (Type)

GraphQL의 가장 큰 특징이자 심장이라고 할 수 있는 게 바로 '스키마'야. 스키마는 API가 제공할 수 있는 모든 데이터의 종류와 그 관계를 정의한 '설계도' 또는 '메뉴판' 같은 거야. 이 스키마는 SDL(Schema Definition Language)이라는 직관적인 문법으로 작성돼.

예를 들어, 블로그 API의 스키마를 한번 만들어볼까?

# 사용자를 나타내는 타입
type User {
  id: ID!
  name: String!
  email: String
}

# 게시글을 나타내는 타입
type Post {
  id: ID!
  title: String!
  content: String!
  author: User! # Post와 User는 관계가 있어!
  comments: [Comment!] # 댓글은 여러 개일 수 있지
}

# 댓글을 나타내는 타입
type Comment {
  id: ID!
  text: String!
  author: User!
}

# 클라이언트가 데이터를 요청(조회)할 수 있는 진입점
type Query {
  post(id: ID!): Post
  allPosts: [Post!]
  me: User
}

어때? 코드를 잘 몰라도 대충 어떤 데이터가 있는지, `Post` 타입 안에는 `author`라는 `User` 타입의 필드가 있다는 관계까지 한눈에 보이지? `String!`, `ID!` 에서 `!`는 '이 필드는 절대 null이 될 수 없다(Non-Nullable)'는 뜻이야. 이렇게 GraphQL은 강력한 타입 시스템을 기반으로 하기 때문에, API의 구조가 명확해지고 개발 과정에서 실수를 줄여줘. 이 스키마 자체가 완벽한 API 문서 역할을 하는 거지.

2. 단 하나의 엔드포인트 (Single Endpoint)

REST가 `/users`, `/posts` 등 수많은 엔드포인트를 가지는 것과 달리, GraphQL은 보통 `/graphql`이라는 단 하나의 엔드포인트만 사용해. 모든 요청은 이 엔드포인트로 보내지. 그럼 어떻게 다른 작업을 구분하냐고? 바로 요청 본문에 담긴 '쿼리' 내용을 보고 서버가 알아서 판단해.

3. 쿼리 (Query) - 데이터 읽기

클라이언트가 서버로부터 데이터를 가져오고 싶을 때 사용하는 게 바로 '쿼리'야. 클라이언트는 스키마에 정의된 내용을 바탕으로, 자신이 필요한 데이터 필드만 콕 집어서 요청할 수 있어.

예를 들어, 1번 게시글의 '제목'과 '작성자의 이름'만 필요하다고 해보자.

클라이언트 요청 (Query):

query GetPostTitleAndAuthor {
  post(id: "1") {
    title
    author {
      name
    }
  }
}

요청문의 구조가 JSON과 비슷해서 직관적이지? `post` 필드를 요청하면서 `id`가 "1"인 것을 원하고, 그 결과물 중에서는 `title`과 `author`의 `name`만 달라고 명시한 거야.

서버 응답 (JSON):

{
  "data": {
    "post": {
      "title": "REST API는 정말 최고야!",
      "author": {
        "name": "김개발"
      }
    }
  }
}

놀랍지 않아? 서버는 클라이언트가 요청한 구조와 완벽하게 동일한 모양으로 데이터를 돌려줬어. 게시글의 `content`나 작성자의 `email` 같은 불필요한 데이터는 전혀 포함되지 않았지. 이게 바로 GraphQL이 오버페칭 문제를 해결하는 방식이야.

또한, 게시글 정보와 작성자 정보를 한 번의 요청으로 가져왔지? REST였다면 `/posts/1`과 `/users/{authorId}` 두 번 요청해야 했을 텐데 말이야. 이렇게 언더페칭 문제도 동시에 해결돼.

4. 뮤테이션 (Mutation) - 데이터 쓰기

데이터를 생성, 수정, 삭제하는 작업은 '뮤테이션'을 통해 이루어져. 쿼리가 읽기(Read) 전용인 것과 달리, 뮤테이션은 쓰기(Write) 작업을 담당해. 의도적으로 분리해서 API의 부수 효과(side effect)를 명확하게 관리하려는 철학이 담겨있어.

새로운 게시글을 작성하는 뮤테이션을 만들어볼까?

스키마 정의 (Mutation 타입 추가):

type Mutation {
  createPost(title: String!, content: String!, authorId: ID!): Post
}

클라이언트 요청 (Mutation):

mutation CreateNewPost {
  createPost(title: "GraphQL 첫걸음", content: "뮤테이션은 이렇게 쓰는구나!", authorId: "user-123") {
    id
    title
    createdAt
    author {
      name
    }
  }
}

뮤테이션의 멋진 점은, 데이터를 변경한 직후에 새롭게 생성되거나 변경된 데이터를 바로 조회할 수 있다는 거야. 위 예시에서는 게시글을 생성한 후, 그 결과로 생성된 게시글의 `id`, `title`, `createdAt`, 그리고 작성자의 `name`까지 한 번에 받아오고 있어. REST였다면 `POST` 요청 후에 다시 `GET` 요청을 보내야 했을 텐데, 이 과정이 한 번에 해결되는 거지.

5. 서브스크립션 (Subscription) - 실시간 데이터

GraphQL의 또 다른 강력한 무기는 바로 '서브스크립션'이야. 이건 특정 이벤트가 발생했을 때 서버가 클라이언트에게 실시간으로 데이터를 푸시(push)해주는 기능이야. 보통 웹소켓(WebSocket)을 통해 구현돼.

예를 들어, 채팅 앱에서 새로운 메시지가 오거나, 협업 툴에서 누군가 문서를 수정했을 때 실시간으로 업데이트되는 기능을 서브스크립션으로 아주 우아하게 만들 수 있어.

클라이언트 요청 (Subscription):

subscription OnNewComment {
  newComment(postId: "1") {
    id
    text
    author {
      name
    }
  }
}

이렇게 구독을 걸어두면, 1번 게시글에 새로운 댓글이 달릴 때마다 서버가 클라이언트에게 위에서 요청한 형태의 댓글 데이터를 보내주는 거야. REST에서는 이런 실시간 기능을 구현하려면 별도의 기술(Polling, WebSocket 등)을 따로 구현해야 했지만, GraphQL은 이걸 표준 사양으로 포함하고 있어.

GraphQL의 빛과 그림자 ✨🌪️

GraphQL은 분명 많은 문제를 해결해주는 혁신적인 기술이지만, 역시나 만병통치약은 아니야. 장점만큼이나 고려해야 할 단점들도 존재해.

👍 GraphQL의 장점 (빛)

• 데이터 페칭 효율성 극대화: 오버페칭과 언더페칭 문제를 근본적으로 해결해. 클라이언트가 필요한 데이터만 정확하게 받아오므로 네트워크 사용량을 줄이고 앱 성능을 향상시킬 수 있어.
• 강력한 타입 시스템과 자기 문서화: 스키마 자체가 완벽한 API 문서 역할을 해. 프론트엔드와 백엔드 개발자 간의 소통 오류를 줄여주고, 타입 체크를 통해 안정성을 높여줘.
• 프론트엔드 개발 생산성 향상: 필요한 데이터 구조가 바뀌어도 백엔드 API가 수정될 때까지 기다릴 필요가 없어. 프론트엔드에서 필요한 쿼리만 수정하면 되니까 개발 속도가 빨라져.
• 진화하는 API: REST처럼 버전을 관리할 필요 없이, 기존 필드는 유지한 채 새로운 필드를 추가하거나, 더 이상 사용하지 않는 필드는 `@deprecated` 지시어로 사용 중단을 표시할 수 있어. API를 점진적으로 발전시키기 용이해.
• 실시간 기능 내장: 서브스크립션을 통해 실시간 데이터 통신을 표준화된 방식으로 쉽게 구현할 수 있어.

👎 GraphQL의 단점 (그림자)

• 높은 학습 곡선: REST에 비해 배워야 할 개념(스키마, 쿼리, 리졸버 등)이 많고, 서버 구축도 더 복잡해. 특히 '리졸버'를 어떻게 효율적으로 설계하느냐가 성능의 관건인데, 여기서 N+1 문제가 발생하지 않도록 데이터로더(DataLoader) 같은 기술을 함께 사용해야 하는 등 고려할 게 많아.
• 복잡한 캐싱: REST는 URL 기반이라 HTTP 표준 캐싱을 그대로 활용하기 쉽지만, GraphQL은 단일 엔드포인트에 `POST` 요청을 사용하므로 HTTP 레벨의 캐싱이 거의 불가능해. 아폴로 클라이언트(Apollo Client)나 릴레이(Relay) 같은 전문 라이브러리를 사용해 클라이언트 단에서 정교한 캐싱 전략을 구현해야 해.
• 파일 업로드: GraphQL 명세에는 파일 업로드에 대한 표준 방식이 없어. `multipart/form-data` 요청을 처리하기 위한 별도의 라이브러리나 구현이 필요해.
• 보안 및 성능 이슈: 사용자가 너무 복잡하고 깊은 쿼리(예: `post { author { posts { author { ... } } } }`)를 보내면 서버에 엄청난 부하를 줄 수 있어. 이를 방지하기 위해 쿼리 깊이 제한, 타임아웃, 비용 분석 같은 추가적인 보호 장치가 반드시 필요해.
• 미성숙한 생태계 (과거형): 초창기에는 REST에 비해 도구나 라이브러리가 부족했지만, 지금은 아폴로(Apollo)와 릴레이(Relay)를 중심으로 생태계가 매우 빠르게 성장해서 이 단점은 많이 희석되었어.

Chapter 3. 그래서 뭘 써야 할까? 선택의 기로에서 🤔

자, 지금까지 REST와 GraphQL이라는 두 거인의 특징을 속속들이 파헤쳐 봤어. 둘 다 훌륭한 기술이지만, 성격이 너무 다르지? 이제 가장 중요한 질문이 남았어. "내 프로젝트에는 어떤 기술을 써야 할까?"

이건 마치 "짜장면이 좋아요, 짬뽕이 좋아요?" 같은 질문과 비슷해. 정답은 없어. 오직 '상황에 맞는 더 나은 선택'만 있을 뿐이야. 몇 가지 시나리오를 통해 언제 어떤 기술이 더 빛을 발하는지 알아보자.

이럴 땐 주저 없이 REST API!

1. 단순하고 직관적인 CRUD API가 필요할 때

프로젝트의 요구사항이 복잡하지 않고, 데이터를 생성(Create), 조회(Read), 수정(Update), 삭제(DELETE)하는 기능이 대부분이라면 REST가 정답에 가까워. 간단한 블로그, 관리자 페이지, 내부 시스템 연동 등 자원의 구조가 명확하고 예측 가능한 경우, REST의 단순함이 오히려 큰 장점이 돼. GraphQL의 복잡한 설정 없이도 빠르고 쉽게 API를 구축할 수 있지.

2. HTTP 캐싱을 적극적으로 활용해야 할 때

이미지나 동영상, 혹은 자주 바뀌지 않는 공지사항 같은 정적 콘텐츠를 많이 다루는 서비스라면 REST의 캐싱 능력은 정말 강력해. `GET` 요청에 대한 응답을 CDN이나 브라우저에 캐싱해서 서버 부하를 획기적으로 줄이고 사용자 경험을 높일 수 있어. GraphQL로는 구현하기 훨씬 까다로운 부분이야.

3. 공개 API(Public API)를 만들어야 할 때

외부 개발자들이 사용할 공개 API를 만든다면, 범용성과 낮은 진입장벽이 중요해. REST는 이미 웹 개발의 표준과 같아서 대부분의 개발자에게 익숙해. 복잡한 쿼리 문법을 따로 배우지 않아도 쉽게 사용할 수 있다는 건 큰 장점이지. 또한, 요청을 제어하기가 더 쉬워서 API 사용량을 추적하고 제한(Rate Limiting)하는 정책을 적용하기에도 용이해.

4. 팀이 REST에 매우 익숙하고, 빠르게 프로토타입을 만들어야 할 때

개발은 결국 사람이 하는 일이야. 팀원들이 REST 생태계에 대한 깊은 이해와 경험을 가지고 있다면, 굳이 새로운 기술을 도입하며 학습 비용을 치를 필요가 없을 수도 있어. 특히 빠르게 시장의 반응을 확인해야 하는 초기 스타트업이라면, 익숙한 기술로 신속하게 MVP(최소 기능 제품)를 만드는 것이 더 현명한 전략일 수 있지.

이런 상황이라면 GraphQL이 정답!

1. 다양한 클라이언트(Web, iOS, Android)를 동시에 지원해야 할 때

웹사이트, 아이폰 앱, 안드로이드 앱이 각각 필요로 하는 데이터의 종류와 양이 다르다면 GraphQL이 최고의 선택이야. 데스크톱 웹에서는 고화질 이미지와 상세 정보가 필요하지만, 모바일 앱에서는 저화질 썸네일과 핵심 정보만 필요할 수 있잖아? GraphQL을 사용하면 각 클라이언트가 자신에게 필요한 데이터만 정확히 요청할 수 있어서, 하나의 백엔드로 모든 클라이언트를 효율적으로 지원할 수 있어.

2. 데이터 관계가 복잡하고 중첩된 서비스일 때

소셜 네트워크, 이커머스 플랫폼, 협업 툴처럼 데이터 간의 관계가 거미줄처럼 얽혀있는 서비스라면 GraphQL이 빛을 발해. 예를 들어 '특정 그룹에 속한 유저들이 작성한 게시글에 달린 댓글들' 같은 복잡한 데이터를 REST로 가져오려면 수많은 API 호출이 필요하지만, GraphQL은 단 한 번의 쿼리로 깔끔하게 해결할 수 있어.

3. 프론트엔드와 백엔드의 독립적인 개발이 중요할 때

프론트엔드 팀이 화면 기획 변경에 따라 필요한 데이터를 유연하게 바꾸고 싶어 하고, 백엔드 팀의 작업에 의존하고 싶지 않다면 GraphQL이 이상적이야. 스키마라는 약속 하에, 프론트엔드 개발자는 필요한 쿼리를 마음껏 조합하며 빠르게 프로토타이핑하고 기능을 개발할 수 있어. 백엔드 팀은 비즈니스 로직과 데이터 제공에만 집중하면 되니, 팀 간의 병목 현상이 크게 줄어들지.

4. 실시간 기능이 서비스의 핵심일 때

채팅, 라이브 방송, 실시간 알림, 공동 편집 기능 등 사용자 간의 즉각적인 상호작용이 중요한 서비스라면 GraphQL의 서브스크립션 기능은 매우 매력적인 옵션이야. 실시간 통신을 위한 별도의 서버나 복잡한 구현 없이도, GraphQL의 표준화된 방식으로 안정적인 실시간 기능을 구축할 수 있어.

하이브리드: 두 기술의 장점을 모두 취하는 전략 🤝

"꼭 둘 중 하나만 선택해야 하나요?" 좋은 질문이야. 정답은 '아니'야. 실제 많은 기업에서는 REST와 GraphQL을 함께 사용하는 하이브리드 전략을 취하고 있어.

GraphQL Wrapper / API Gateway

가장 흔한 방법은 기존에 잘 운영되던 REST API들 앞에 GraphQL 서버를 '게이트웨이'처럼 두는 거야. 이 GraphQL 서버는 클라이언트로부터 GraphQL 쿼리를 받아서, 내부적으로 필요한 REST API들을 호출하고 데이터를 조합한 뒤, 다시 클라이언트에게 GraphQL 형태로 응답해줘.

이 방식의 장점은 기존의 안정적인 REST 인프라를 그대로 활용하면서, 클라이언트 단에는 GraphQL의 유연성을 제공할 수 있다는 거야. 대규모 마이크로서비스 아키텍처(MSA) 환경에서 여러 서비스의 API를 하나로 통합하여 제공하는 창구 역할로도 아주 훌륭해.

목적에 따른 분리 사용

서비스의 기능에 따라 기술을 분리해서 사용할 수도 있어. 예를 들어, 외부 개발자들을 위한 공개 API나 파일 업로드/다운로드처럼 단순한 기능은 REST로 구현하고, 내부적으로 사용하는 모바일 앱이나 복잡한 웹 애플리케이션을 위한 API는 GraphQL로 구현하는 거지. 각 기술의 장점을 가장 잘 살릴 수 있는 곳에 배치하는 현명한 방법이야.

Chapter 4. 미래를 향하여: API의 진화는 계속된다 🚀

REST와 GraphQL의 대결은 단순히 기술의 우열을 가리는 것이 아니라, 변화하는 개발 환경과 요구사항에 어떻게 더 잘 대응할 것인가에 대한 고민의 결과물이야. 웹의 탄생과 함께 성장한 REST는 안정성과 범용성을 무기로 여전히 건재하고, 모바일 시대의 복잡성을 해결하기 위해 태어난 GraphQL은 유연성과 효율성을 바탕으로 빠르게 세력을 확장하고 있지.

하지만 기술의 진화는 여기서 멈추지 않아.

• gRPC: 구글이 개발한 고성능 원격 프로시저 호출(RPC) 프레임워크야. HTTP/2를 기반으로 하며, 프로토콜 버퍼(Protocol Buffers)를 사용해 데이터를 직렬화하므로 매우 빠르고 효율적이야. 특히 마이크로서비스 간의 내부 통신에서 REST보다 훨씬 뛰어난 성능을 보여줘.
• tRPC: '타입스크립트(TypeScript)를 위한 RPC'라는 컨셉으로, 별도의 스키마 정의나 코드 생성 없이 타입스크립트의 타입 추론 기능을 100% 활용하는 기술이야. 프론트엔드와 백엔드 모두 타입스크립트를 사용한다면, 마치 하나의 프로젝트에서 함수를 호출하듯 놀랍도록 안전하고 편안한 API 개발 경험을 제공해줘.

이처럼 API 기술은 '어떻게 하면 더 효율적이고, 더 안전하고, 더 편하게 데이터를 주고받을 수 있을까?'라는 질문에 답하며 끊임없이 발전하고 있어.