RESTful API 설계 가이드: HTTP 상태 코드, 메서드, 요청/응답 구조

RESTful API 설계 가이드: 핵심 요소 완벽 이해

RESTful API는 웹 서비스의 표준으로 자리 잡았으며, 그 핵심은 HTTP 프로토콜을 효과적으로 활용하는 데 있습니다. 본 가이드는 RESTful API 설계 시 반드시 고려해야 할 HTTP 메서드, 상태 코드, 그리고 요청/응답 구조에 대한 명확한 이해와 실질적인 적용 방법을 제시합니다.

1. HTTP 메서드 (HTTP Methods)

HTTP 메서드는 클라이언트가 서버에게 어떤 행동을 원하는지를 나타냅니다. RESTful API에서는 각 메서드를 자원에 대한 특정 작업과 매핑하여 사용합니다.

• GET: 자원을 조회합니다. 데이터를 변경하지 않으며, idempotent(멱등성)을 가집니다. (동일한 요청을 여러 번 보내도 결과가 항상 동일)
  • 사용 예: /users (모든 사용자 조회), /users/123 (ID가 123인 사용자 조회)
• POST: 새로운 자원을 생성합니다. idempotent하지 않습니다. (여러 번 보내면 여러 개의 리소스가 생성될 수 있음)
  • 사용 예: /users (새로운 사용자 생성)
• PUT: 기존 자원을 전체적으로 업데이트하거나, 존재하지 않으면 새로 생성합니다. idempotent합니다. (동일한 요청을 여러 번 보내도 결과가 항상 동일)
  • 사용 예: /users/123 (ID가 123인 사용자 정보 전체 업데이트)
• PATCH: 기존 자원의 일부를 업데이트합니다. idempotent하지 않을 수도 있습니다.
  • 사용 예: /users/123 (ID가 123인 사용자 정보 일부 필드 업데이트)
• DELETE: 자원을 삭제합니다. idempotent합니다.
  • 사용 예: /users/123 (ID가 123인 사용자 삭제)

왜 올바른 메서드를 사용해야 하는가?

• API의 의도를 명확히 합니다.
• 클라이언트와 서버 간의 통신을 예측 가능하게 만듭니다.
• 캐싱, 보안 등 HTTP의 기본 기능을 효과적으로 활용할 수 있게 합니다.

2. HTTP 상태 코드 (HTTP Status Codes)

상태 코드는 클라이언트의 요청이 서버에서 어떻게 처리되었는지를 나타내는 3자리 숫자입니다. RESTful API에서는 클라이언트가 요청의 성공 여부와 원인을 쉽게 파악할 수 있도록 표준 상태 코드를 정확하게 반환해야 합니다.

• 2xx (Success): 요청이 성공적으로 처리되었음을 나타냅니다.
  • 200 OK: 요청이 성공적으로 처리되었습니다. (GET, PUT, PATCH, DELETE 시)
  • 201 Created: 요청이 성공적으로 처리되어 새로운 자원이 생성되었습니다. (POST 시)
  • 204 No Content: 요청이 성공적으로 처리되었으나, 응답 본문에 반환할 내용이 없습니다. (DELETE 요청 후)
• 3xx (Redirection): 클라이언트가 요청을 완료하기 위해 추가적인 조치를 취해야 함을 나타냅니다.
  • 301 Moved Permanently: 요청한 자원이 영구적으로 다른 URL로 이동했습니다.
  • 304 Not Modified: 클라이언트가 요청한 자원이 서버에 없지만, 캐시된 버전이 유효함을 나타냅니다.
• 4xx (Client Error): 클라이언트의 요청에 오류가 있음을 나타냅니다.
  • 400 Bad Request: 클라이언트의 요청이 잘못되었습니다. (잘못된 요청 형식, 누락된 필드 등)
  • 401 Unauthorized: 요청에 인증이 필요하거나 인증에 실패했습니다.
  • 403 Forbidden: 클라이언트가 해당 자원에 접근할 권한이 없습니다.
  • 404 Not Found: 요청한 자원을 찾을 수 없습니다.
  • 405 Method Not Allowed: 요청한 HTTP 메서드가 해당 자원에 허용되지 않습니다.
  • 409 Conflict: 요청이 서버의 현재 상태와 충돌합니다.
• 5xx (Server Error): 서버에서 요청을 처리하는 중에 오류가 발생했음을 나타냅니다.
  • 500 Internal Server Error: 서버 내부 오류가 발생했습니다.
  • 503 Service Unavailable: 서버가 일시적으로 요청을 처리할 수 없습니다.

상태 코드 사용 시 주의사항

• 가능한 표준 상태 코드를 사용하고, 커스텀 코드는 최소화합니다.
• 에러 응답 시에는 4xx 또는 5xx 코드와 함께 에러의 원인을 설명하는 메시지(JSON 형식)를 포함하여 클라이언트가 문제를 해결하도록 돕습니다.

3. 요청 및 응답 구조 (Request and Response Structure)

데이터의 형식과 구조는 API의 사용성과 유지보수성에 큰 영향을 미칩니다.

• 데이터 형식: JSON이 사실상의 표준입니다. XML도 사용될 수 있지만, JSON이 더 간결하고 파싱하기 쉽습니다.
• 요청 본문 (Request Body):
  • POST, PUT, PATCH 메서드에서 사용됩니다.
  • 데이터는 JSON 형식으로 전송하는 것이 일반적입니다.
  • Content-Type 헤더에 application/json을 명시합니다.
• 응답 본문 (Response Body):
  • GET 메서드에서 주로 사용되어 자원 정보를 반환합니다.
  • 성공 시에는 요청된 자원 정보 또는 관련 정보를 JSON 형식으로 반환합니다.
  • 오류 시에는 에러 메시지, 에러 코드 등을 포함한 JSON 객체를 반환합니다.
  • Content-Type 헤더에 application/json을 명시합니다.

모범 사례

• 일관성: API 전반에 걸쳐 일관된 필드명(예: camelCase 또는 snake_case)과 데이터 형식을 사용합니다.
• 명확성: 필드명은 데이터의 의미를 명확하게 나타내도록 작성합니다.
• 관계 표현: 관련 자원 간의 링크(HATEOAS)를 포함하여 API 탐색을 용이하게 할 수 있습니다.
• 버전 관리: API 변경 시 하위 호환성을 유지하기 위해 URL(예: /v1/users) 또는 헤더를 통해 버전을 관리합니다.

간단한 예시 (사용자 정보 조회)

• 요청: GET /users/123
• 응답 (200 OK):

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

• 응답 (404 Not Found):

  {
    "error": {
      "code": "resource_not_found",
      "message": "User with ID 123 not found."
    }
  }
  

이 가이드를 기반으로 RESTful API를 설계하면, 더 견고하고 이해하기 쉬우며 유지보수가 용이한 웹 서비스를 구축할 수 있습니다.