![image](https://memgraph.com/_next/image?url=%2Fimages%2Fblog%2Fgraphql-vs-rest-api%2Fcover.png&w=1920&q=75)

# 개요

> 2025년 현재, 클라이언트-서버 API 설계에는 두 가지 주요 접근 방식이 있습니다. REST API는 20년 넘게 업계 표준이었고, GraphQL은 2015년 오픈소스화 이후 빠르게 성장했습니다. 둘 다 프로덕션에서 충분히 검증되었으며, "최고"의 선택은 프로젝트 요구사항에 따라 달라집니다.

---
# REST API

## 핵심 개념

- HTTP 메서드(GET, POST, PUT, DELETE)를 사용한 리소스 기반 아키텍처
- 각 리소스는 고유한 URL을 가짐 (/users/123, /posts/456)
- JSON 형식의 응답 (사실상 표준)
- Stateless 통신

## 장점
### 1. 낮은 학습 곡선

- 대부분의 개발자가 이미 알고 있음
- HTTP 표준을 그대로 활용
- 새 팀원 온보딩이 빠름

### 2. 강력한 캐싱
```javascript
// HTTP 캐싱을 그대로 활용
GET /api/users/123
Cache-Control: max-age=3600
ETag: "abc123"

// CDN, 브라우저 캐시 모두 자동으로 동작
```
### 3. 성숙한 생태계

- Postman, Insomnia 같은 테스트 도구
- OpenAPI/Swagger로 자동 문서화
- 모든 HTTP 클라이언트 라이브러리 호환
- AWS API Gateway, Nginx 등 인프라 지원 완벽

### 4. 명확한 의미론
```javascript
GET    /api/posts      // 목록 조회
POST   /api/posts      // 생성
GET    /api/posts/123  // 단건 조회
PUT    /api/posts/123  // 전체 수정
PATCH  /api/posts/123  // 부분 수정
DELETE /api/posts/123  // 삭제
```
### 5. 디버깅 용이

- 브라우저 Network 탭에서 바로 확인
- curl 한 줄로 테스트 가능
- 로그에서 URL만 봐도 무슨 요청인지 파악

## 단점
### 1. Over-fetching
```javascript
// 사용자 이름만 필요한데 모든 필드를 받음
GET /api/users/123
{
  "id": 123,
  "name": "홍길동",           // 필요한 필드
  "email": "hong@example.com",  // 불필요
  "phone": "010-1234-5678",     // 불필요
  "address": { ... },            // 불필요
  "created_at": "...",           // 불필요
  "updated_at": "..."            // 불필요
}
```

### 2. Under-fetching (N+1 문제)
```javascript
// 게시글 목록
GET /api/posts
[{ id: 1, title: "...", author_id: 10 }, ...]
`
// 각 게시글의 작성자 정보를 가져오려면 추가 요청 필요
GET /api/users/10
GET /api/users/11
GET /api/users/12
// ...

// 또는 엔드포인트를 추가로 만들어야 함
GET /api/posts?include=author
```

### 3. 버전 관리의 복잡성
```javascript
// API가 변경되면 버전을 올려야 함
/api/v1/users  // 구버전 유지
/api/v2/users  // 신규 필드 추가
/api/v3/users  // 구조 변경

// 여러 버전을 동시에 유지보수해야 함
```

### 4. 엔드포인트 폭발
```javascript
// 다양한 요구사항에 맞춰 엔드포인트가 계속 추가됨
GET /api/posts
GET /api/posts?status=published
GET /api/posts?author=123
GET /api/posts?author=123&status=published
GET /api/posts/trending
GET /api/posts/recommended
GET /api/users/123/posts
// ...
실무 예시
javascript// 사용자 정보와 최근 게시글 5개를 가져오려면
const user = await fetch('/api/users/123').then(r => r.json());
const posts = await fetch(`/api/users/123/posts?limit=5`).then(r => r.json());

// 2번의 네트워크 요청 필요
// 각 게시글의 댓글 수까지 필요하면 3번째 요청 또는 복잡한 엔드포인트 설계 필요
```
---
# GraphQL
## 핵심 개념

> - Facebook(현 Meta)이 2012년 개발, 2015년 오픈소스화
> - 쿼리 언어로 클라이언트가 필요한 데이터 구조를 명시
> - 단일 엔드포인트 (POST /graphql)
> - 강력한 타입 시스템 (Schema Definition Language)
> - 현재는 Linux Foundation 산하 GraphQL Foundation에서 관리

## 장점
### 1. 정확한 데이터 요청

```graphql
query {
  user(id: 123) {
    name          # 필요한 필드만 명시
    email
  }
}

# 응답
{
  "data": {
    "user": {
      "name": "홍길동",
      "email": "hong@example.com"
    }
  }
}
```
### 2. 단일 요청으로 복잡한 데이터 구조
```graphql
query {
  user(id: 123) {
    name
    email
    posts(limit: 5) {
      title
      createdAt
      comments(limit: 3) {
        content
        author {
          name
          avatar
        }
      }
    }
  }
}

# 한 번의 요청으로 사용자 → 게시글 → 댓글 → 작성자 모두 가져옴
```
### 3. 강력한 타입 시스템
```graphql
type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  comments: [Comment!]!
}

# IDE에서 자동완성, 타입 체크 가능
# 컴파일 타임에 오류 발견
```

### 4. 버전 관리 불필요
```graphql
type User {
  id: ID!
  name: String!
  email: String!
  phone: String @deprecated(reason: "Use phoneNumber instead")
  phoneNumber: String
}

# 필드 추가/deprecated만으로 관리
# 클라이언트는 필요한 필드만 요청하므로 호환성 유지
```

### 5. 자가 문서화
```graphql
# 스키마 자체가 문서
# GraphQL Playground에서 모든 타입, 필드, 인자 확인 가능
# 별도 문서 작성 불필요
6. 실시간 기능 (Subscriptions)
graphqlsubscription {
  newMessage(chatId: "123") {
    id
    content
    author {
      name
    }
  }
}

# WebSocket으로 실시간 업데이트
# 채팅, 알림, 실시간 대시보드 구현 용이
```
## 단점
### 1. 학습 곡선

- GraphQL 쿼리 언어 학습 필요
- Schema 설계 패턴 학습 필요
- Resolver 개념 이해 필요
- 팀 전체가 익숙해지기까지 시간 소요

### 2. 캐싱 복잡성
```javascript
// REST는 URL 기반 캐싱
GET /api/users/123 → 캐시 키: /api/users/123

// GraphQL은 쿼리 내용이 캐시 키
// POST 요청이라 HTTP 캐싱 불가
// Apollo Client, urql 같은 전용 캐싱 필요
```
### 3. 쿼리 복잡도 관리
```graphql
# 악의적이거나 비효율적인 쿼리 가능
query {
  users {
    posts {
      comments {
        author {
          posts {
            comments {
              # 무한 중첩...
            }
          }
        }
      }
    }
  }
}

# Depth limiting, Query complexity analysis 필수
```

### 4. N+1 문제
```javascript
// Resolver가 비효율적이면 성능 문제
const resolvers = {
  Post: {
    author: (post) => {
      return db.users.findById(post.authorId); // 각 게시글마다 DB 쿼리!
    }
  }
};

// DataLoader로 해결 필요
const userLoader = new DataLoader(ids => 
  db.users.findByIds(ids) // 배치 처리
);
```

### 5. 파일 업로드
```javascript
// GraphQL 표준이 아님
// multipart/form-data 별도 구현 필요
// 또는 별도 REST 엔드포인트 사용
```
### 6. 에러 처리
```javascript
// HTTP 상태 코드를 활용할 수 없음
// 쿼리 일부만 실패해도 200 OK 반환
{
  "data": {
    "user": null  // 실패
  },
  "errors": [{
    "message": "User not found",
    "path": ["user"]
  }]
}

// 클라이언트가 data와 errors를 모두 확인해야 함
```

## 실무 예시
```javascript
// Apollo Client 예시
const { data, loading, error } = useQuery(
gql`
  query GetUserWithPosts($userId: ID!) {
    user(id: $userId) {
      name
      email
      posts(limit: 5) {
        title
        createdAt
        commentCount  # 서버에서 계산된 필드
      }
    }
  }
`,{
  variables: { userId: '123' }
});

// 한 번의 요청으로 모든 데이터
// 타입 안정성 보장
// 캐싱 자동 처리
```
---
# 성능 비교 (2025년 기준)
- 페이로드 크기
```javascript
// REST - 불필요한 필드 포함
{
  "id": 123,
  "name": "홍길동",
  "email": "hong@example.com",
  "phone": "010-1234-5678",
  "address": { /* ... */ },
  "preferences": { /* ... */ },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2025-02-20T14:20:00Z"
}
// ~800 bytes

// GraphQL - 필요한 필드만
{
  "data": {
    "user": {
      "name": "홍길동",
      "email": "hong@example.com"
    }
  }
}
// ~150 bytes
```

**실측 데이터** (복잡한 중첩 쿼리 기준):
- REST: 평균 3-5개 요청, 총 ~2-3MB
- GraphQL: 1개 요청, ~800KB

## 네트워크 레이턴시

### REST: 
1. 요청 1: 사용자 정보 (100ms)
2. 요청 2: 게시글 목록 (120ms)  
3. 요청 3: 댓글 수 (90ms)
4. 총: ~310ms + 네트워크 오버헤드

### GraphQL:
1. 단일 요청: ~180ms

## 개발 속도

1. REST: 프론트엔드가 새 데이터 필요 → 백엔드 엔드포인트 추가 → 배포 → 사용
2. GraphQL: 프론트엔드가 새 데이터 필요 → 스키마에 이미 있으면 바로 쿼리 작성
---

# 2025년 실무 트렌드
## **REST**가 여전히 우세한 영역
### 1. 공개 API
```javascript
// Stripe, GitHub, Twilio 등 대부분의 공개 API는 REST
GET https://api.stripe.com/v1/customers/cus_xxx
Authorization: Bearer sk_xxx
```

외부 개발자가 사용하기 쉬움
문서화가 직관적
curl로 바로 테스트 가능

### 2. 간단한 CRUD 애플리케이션
```javascript
// To-do 앱, 블로그, 간단한 관리 시스템
GET /api/todos
POST /api/todos
PUT /api/todos/123
DELETE /api/todos/123
```
### 3. 레거시 시스템 통합

- 기존 REST API 인프라 활용
- 마이그레이션 비용 없음

## GraphQL이 강세인 영역
### 1. 모바일 앱
```graphql
# 데이터 사용량 최소화
# 배터리 절약
# 3G/4G 환경에서도 빠른 응답
query {
  feed(limit: 10) {
    id
    thumbnail  # 작은 이미지만
    title
  }
}
```
### 2. 복잡한 데이터 관계
```graphql
# E-commerce, SNS, 협업 도구
query {
  product(id: "123") {
    name
    price
    reviews(limit: 5) {
      rating
      comment
      author {
        name
        verified
      }
    }
    relatedProducts(limit: 3) {
      name
      price
      thumbnail
    }
  }
}
```

### 3. BFF (Backend For Frontend) 패턴
*BFF패턴에 대해선 나중에 따로 다룰 예정입니다*

### 4. 실시간 대시보드
```graphql
subscription {
  orderUpdates {
    orderId
    status
    timestamp
  }
}
# WebSocket으로 실시간 업데이트
```
---

# 선택 가이드
## REST API가 적합할 경우:
1. 공개 API 또는 파트너 API
2. 간단한 CRUD 위주 애플리케이션
3. 팀이 GraphQL 학습 시간이 없는 경우
4. HTTP 캐싱을 적극 활용하고 싶은 경우
5. 레거시 시스템과 통합해야 하는 경우
6. 파일 업로드/다운로드가 주요 기능인 경우

### 구체적 예시:

1. 블로그 플랫폼 (Medium, WordPress)
2. 결제 서비스 API (Stripe, PayPal)
3. OAuth 인증 서비스
4. 간단한 관리자 대시보드


## GraphQL이 적합할 경우:

1. 모바일 앱 (데이터 효율성 중요)
2. 복잡한 데이터 관계가 많은 경우
3. 프론트엔드 요구사항이 자주 변경되는 경우
4. 실시간 기능이 필요한 경우
5. 여러 데이터 소스를 통합하는 BFF 구축
6. 타입 안정성이 중요한 경우

### 구체적 예시:

1. SNS 플랫폼 (Facebook, Instagram)
2. E-commerce (Shopify)
3. 협업 도구 (Notion, Slack)
4. 복잡한 SaaS 대시보드

---
# 실제 기업 사례 (2025년)

## REST 사용사례

- Stripe: 결제 API (외부 개발자 친화적)
- Twilio: SMS/음성 API
- AWS: 대부분의 AWS 서비스

## GraphQL 사용사례

- GitHub: API v4는 GraphQL
- Shopify: Admin API와 Storefront API
- Netflix: 내부 API (Falcor, GraphQL 유사)

## 둘 다 사용하는 사례

- GitHub: REST (v3) + GraphQL (v4)
- Contentful: REST + GraphQL
- Hasura: 자동으로 DB에서 GraphQL 생성

## 하이브리드 접근
실무에서는 둘을 함께 사용하는 경우가 많습니다:
```javascript
// 공개 API: REST
app.get('/api/v1/products/:id', ...)

// 웹/모바일 앱: GraphQL
app.post('/graphql', graphqlHTTP({ schema }))

// 파일 업로드: REST
app.post('/api/upload', upload.single('file'), ...)

// 실시간 알림: GraphQL Subscription
```
### 장점:
1. 각 기술의 강점을 활용
2. 점진적 마이그레이션 가능
3. 레거시 호환성 유지

## 마이그레이션 전략
REST → GraphQL
```javascript
// 1단계: GraphQL 서버가 REST API를 래핑
const resolvers = {
  Query: {
    user: (_, { id }) => fetch(`/api/users/${id}`).then(r => r.json())
  }
}

// 2단계: 점진적으로 Resolver를 직접 DB 접근으로 변경
const resolvers = {
  Query: {
    user: (_, { id }) => db.users.findById(id)
  }
}

// 3단계: 프론트엔드를 하나씩 GraphQL로 전환
```

### 비용 고려사항

#### **REST 추가 비용** 
- 거의 없음 (표준 HTTP)
####  **GraphQL 추가 비용**
1. 개발: 스키마 설계, Resolver 구현
2. 인프라: Apollo Server, DataLoader 등
3. 모니터링: Query complexity, 성능 추적
4. 학습: 팀 교육 시간

# 결론

**2025년 현재, 둘 다 성숙하고 프로덕션에서 검증된 기술이며 프로젝트에 맞게 사용하는게 중요할 것 같습니다.**

## 실무 추천
### 1. 스타트업/신규 프로젝트:
- 작게 시작: REST로 MVP 개발
- 복잡해지면: GraphQL 고려
- 필요시: 하이브리드 접근

### 2. 대규모 프로젝트:
- 내부용: GraphQL (효율성)
- 외부용: REST (접근성)
- 실시간: GraphQL Subscriptions

# 마지막으로 기술 선택시 가장 중요한 것
1. 팀의 경험
2. 프로젝트 요구사항
3. 장기 유지보수 가능성 고려

# 느낀점
REST API는 워낙 익숙하게 써오다 보니 크게 생각하지 않았지만, 블로그를 만들면서 처음 GraphQL을 제대로 다뤄보니 둘의 장단점이 확실히 비교를 할 수 있었습니다.<br />
특히 요즘 GraphQL은 Apollo까지 함께 이해해야 해서 초반에는 머리가 지끈거릴 정도로 어렵고, 학습곡선도 짧지 않지만 그래도 시간이 지나 익숙해지니까 확실히 편한 면이 많았습니다.<br />

개인 프로젝트라도 이렇게 GraphQL을 직접 적용해보고, 그 경험을 바탕으로 글까지 정리해볼 수 있다는 게 참 의미 있고 좋은 기회였던 것 같습니다.

GraphQL vs REST API : 2025년 기준으로 다시 생각해보기

독자의 메모