RESTful API와 GraphQL 비교 및 API 문서 작성법에 관한 메모

RESTful API vs GraphQL 비교

오늘 API 설계 관련 자료를 찾아보면서 RESTful API와 GraphQL의 차이점을 정리해봄

두 방식 모두 자주 사용되는데, 각각의 특징과 장단점을 명확하게 이해하는 것이 중요할 것 같다.

 

■ RESTful API

• 구조: 리소스 중심 구조로, URL 경로를 통해 리소스에 접근
• HTTP 메서드: GET, POST, PUT, DELETE 등을 사용해 CRUD 작업 수행
• 엔드포인트: 리소스마다 다른 엔드포인트 사용 (예: /users, /posts)
• 데이터 가져오기: 필요한 정보를 얻기 위해 여러 엔드포인트에 요청해야 할 수도 있음
• 오버페칭/언더페칭: 종종 필요 이상의 데이터를 받거나, 필요한 데이터를 모두 받지 못하는 경우 발생

GET /api/users/123          // 사용자 정보 조회
GET /api/users/123/posts    // 사용자의 게시물 조회

■ GraphQL

• 구조: 단일 엔드포인트를 통해 쿼리 언어로 필요한 데이터 요청
• 작업 유형: Query(조회), Mutation(수정), Subscription(실시간 업데이트)
• 데이터 요청: 클라이언트가 정확히 필요한 데이터만 지정하여 요청 가능
• 단일 요청: 여러 리소스의 데이터를 하나의 요청으로 가져올 수 있음
• 타입 시스템: 강력한 타입 시스템으로 API 스키마 정의

query {
  user(id: "123") {
    name
    email
    posts {
      title
      content
    }
  }
}

---

주요 차이점 요약

1. 데이터 요청 방식:
   • REST: 여러 엔드포인트에 각각 요청
   • GraphQL: 하나의 엔드포인트에 필요한 데이터 구조를 쿼리로 요청
2. 유연성:
   • REST: 서버에서 정의한 응답 구조로 고정
   • GraphQL: 클라이언트가 필요한 데이터만 요청 가능
3. 버전 관리:
   • REST: 보통 URL에 버전 명시 (예: /api/v1/users)
   • GraphQL: 타입과 필드를 추가/제거하는 방식으로 진화, 명시적 버전 관리 필요성 감소
4. 상태 코드:
   • REST: HTTP 상태 코드로 응답 상태 표현
   • GraphQL: 항상 200 OK 반환하고 에러는 응답 본문에 포함
5. 캐싱:
   • REST: HTTP 표준 캐싱 메커니즘 활용 용이
   • GraphQL: 복잡한 쿼리에 대한 캐싱 구현이 더 어려울 수 있음

---

API 문서 작성 방법

API를 설계한 후에는 문서화가 정말 중요하다. 다른 개발자들이 내 API를 쉽게 이해하고 사용할 수 있도록 명확한 문서를 작성해야 한다.

좋은 API 문서의 요소

1. 개요 및 시작 가이드
   • API의 목적과 주요 기능 설명
   • 인증 방법 및 시작하기 위한 단계별 가이드
2. 엔드포인트 설명
   • 모든 엔드포인트 목록과 각각의 기능
   • HTTP 메서드, URL 구조, 경로 파라미터 설명
3. 요청/응답 예시
   • 각 엔드포인트의 요청 형식과 파라미터
   • 성공/실패 응답 예시와 상태 코드
   • 데이터 형식 및 필드 설명
4. 에러 처리
   • 가능한 에러 코드 목록과 의미
   • 문제 해결을 위한 제안
5. 인증 및 권한
   • 인증 방식 상세 설명 (API 키, OAuth 등)
   • 권한 수준과 제한사항

---

API 문서화 도구

몇 가지 좋은 문서화 도구들:

• Swagger/OpenAPI: RESTful API를 위한 표준 명세 형식과 UI
• Postman: API 테스트와 문서 생성을 동시에 할 수 있음
• Slate: 깔끔한 단일 페이지 문서 생성
• GraphQL Playground/GraphiQL: GraphQL API를 위한 대화형 문서

실용적인 문서화 팁

1. 코드와 함께 문서 유지: 코드 변경 시 문서도 함께 업데이트
2. 예제 중심: 실제 사용 사례와 예제 코드 제공
3. 일관된 형식: 모든 엔드포인트에 동일한 문서화 패턴 적용
4. 버전 관리: API 버전별 문서 관리
5. 대화형 요소: 가능하면 API를 직접 테스트할 수 있는 요소 포함

구현 예시

RESTful API 문서 예시

## 사용자 조회 API

### GET /api/users/{id}

사용자 ID로 특정 사용자 정보를 조회합니다.

**경로 파라미터:**
- `id` (필수): 조회할 사용자의 고유 식별자

**응답:**
- 200 OK: 사용자 정보 반환
  ```json
  {
    "id": "123",
    "name": "홍길동",
    "email": "hong@example.com",
    "created_at": "2023-01-15T09:30:00Z"
  }

• 404 Not Found: 사용자가 존재하지 않음
• 401 Unauthorized: 인증 실패

### GraphQL API 문서 예시
```markdown
## User Query

사용자 정보를 조회하는 쿼리입니다.

**쿼리:**
```graphql
query User($id: ID!) {
  user(id: $id) {
    id
    name
    email
    posts {
      id
      title
    }
  }
}

변수:

{
  "id": "123"
}

응답:

{
  "data": {
    "user": {
      "id": "123",
      "name": "홍길동",
      "email": "hong@example.com",
      "posts": [
        {
          "id": "1",
          "title": "첫 번째 게시물"
        }
      ]
    }
  }
}

 

이렇게 정리해보니 두 방식 모두 장단점이 있어서 프로젝트 특성에 맞게 선택해야 할 것 같다. 

특히 모바일 앱처럼 네트워크 효율성이 중요한 경우는 GraphQL이, 

간단한 CRUD 작업이 주를 이루는 경우는 RESTful API가 더 적합할 수 있겠다. 

문서화는 어떤 방식을 선택하든 필수적인 과정이니 처음부터 신경써서 작성해야겠다.

 

 

RESTful API와 GraphQL 비교 및 API 문서 작성법에 관한 메모