REST API 설계 원칙과 좋은 API 만들기

API는 개발자들이 사용하는 인터페이스입니다. 좋은 API는 직관적이어서 문서를 거의 보지 않아도 쓸 수 있습니다. 나쁜 API는 개발자를 혼란스럽게 만들고, 통합하는 데 오랜 시간을 낭비하게 합니다. 외부에 API를 제공하든 내부에서만 쓰든, 잘 설계된 API는 유지보수를 훨씬 쉽게 만듭니다.

REST API의 기본 원칙

자원(Resource) 중심 URL 설계

REST API는 동사가 아닌 명사(자원)를 중심으로 URL을 설계합니다.

나쁜 예 (동사 중심):

GET /getUsers
POST /createUser
DELETE /deleteUser/123
POST /getUserPosts

좋은 예 (자원 중심):

GET    /users           — 사용자 목록 조회
POST   /users           — 사용자 생성
GET    /users/123       — 특정 사용자 조회
PUT    /users/123       — 특정 사용자 수정
DELETE /users/123       — 특정 사용자 삭제
GET    /users/123/posts — 특정 사용자의 게시글 목록

HTTP 메서드(GET, POST, PUT, DELETE)가 동사 역할을 합니다.

HTTP 메서드의 올바른 사용

메서드	목적	멱등성
GET	조회	예 (여러 번 해도 같은 결과)
POST	생성	아니오
PUT	전체 수정	예
PATCH	부분 수정	아니오 (보통)
DELETE	삭제	예

GET 요청으로 데이터를 변경하거나 삭제하면 절대 안 됩니다.

HTTP 상태 코드 올바른 사용

200 OK            — 성공
201 Created       — 생성 성공 (POST 후)
204 No Content    — 성공이지만 반환 데이터 없음 (DELETE 후)
400 Bad Request   — 잘못된 요청 (입력값 오류)
401 Unauthorized  — 인증 필요
403 Forbidden     — 인증됐지만 권한 없음
404 Not Found     — 자원 없음
409 Conflict      — 충돌 (이미 존재하는 이메일 등)
422 Unprocessable Entity — 유효성 검사 실패
500 Internal Server Error — 서버 오류

모든 오류에 500을 반환하거나, 오류인데 200을 반환하는 것은 피해야 합니다.

일관된 응답 형식

응답 형식을 일관성 있게 유지합니다.

성공 응답:

{
  "data": {
    "id": 123,
    "email": "user@example.com",
    "name": "홍길동"
  }
}

목록 응답 (페이지네이션 포함):

{
  "data": [...],
  "pagination": {
    "total": 150,
    "page": 1,
    "perPage": 20,
    "totalPages": 8
  }
}

에러 응답:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "이메일 형식이 올바르지 않습니다",
    "details": [
      { "field": "email", "message": "유효한 이메일을 입력하세요" }
    ]
  }
}

에러 응답에 사용자에게 보여줄 수 있는 메시지와 개발자가 디버깅에 쓸 수 있는 코드를 함께 포함하세요.

API 버전 관리

API는 한 번 출시하면 기존 클라이언트를 위해 유지해야 합니다. 버전 관리 없이 API를 변경하면 기존 사용자가 깨집니다.

URL 버전 방식 (가장 일반적):

/api/v1/users
/api/v2/users

헤더 버전 방식:

Accept: application/vnd.myapi.v2+json

URL 방식이 더 명시적이고 디버깅하기 쉬워 추천합니다. 새 버전이 안정적으로 운영되면 이전 버전 지원 종료(Sunset) 날짜를 미리 공지하세요.

필터링, 정렬, 페이지네이션

필터링:

GET /posts?status=published&category=tech

정렬:

GET /users?sort=created_at&order=desc

페이지네이션:

GET /users?page=2&perPage=20
# 또는 커서 기반
GET /users?cursor=eyJpZCI6MTIzfQ&limit=20

커서 기반 페이지네이션은 대용량 데이터에서 성능이 좋습니다.

API 문서화

좋은 API라도 문서가 없으면 사용하기 어렵습니다.

OpenAPI (Swagger): API 스펙을 YAML/JSON으로 정의하고 자동으로 문서를 생성합니다. 인터랙티브 문서를 제공해 브라우저에서 직접 API를 테스트할 수 있습니다.

openapi: 3.0.0
paths:
  /users/{id}:
    get:
      summary: 사용자 조회
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 성공

Postman: 팀 내부 API 문서와 테스트에 활용합니다.

API 보안

인증: JWT 또는 API Key를 Authorization 헤더로 전달합니다.

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

Rate Limiting: IP 당 요청 수를 제한하여 남용을 방지합니다.

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1640000000

CORS: 허용된 출처에서만 API를 호출할 수 있게 설정합니다.

좋은 API는 클라이언트 개발자의 경험을 향상시킵니다. 자신이 그 API를 처음 사용하는 개발자라고 생각하면서 설계하면 자연스럽게 좋은 API가 만들어집니다.