HTTP Method 속성

HTTP Method
HTTP Method는 안전성(Safe), 멱등성(Idempotent), 캐시가능성(Cacheable) 속성을 가지고 있다.

속성표

( Optional은 Java의 Optional과 같이 있을 수 있다라는 말과 같다. )

1. 안전성 (Safe)

• 서버의 데이터를 변경하지 않는 메소드를 안전하다고 한다.
• GET: 안전하다. 서버에 저장된 데이터를 조회만 할 뿐 변경하지 않는다.
• POST, DELETE, PUT, PATCH: 안전하지 않다. 데이터를 생성, 수정, 삭제하는 행위를 수행한다.

2. 멱등성 (Idempotent)

• 동일한 요청을 한 번 보내든 여러 번 보내든 항상 결과가 같은 메소드를 멱등하다고 한다.
• GET: 멱등하다. 동일한 조회 요청에 대해 항상 같은 결과가 반환된다. (단, 서버의 데이터가 중간에 변경되는 것은 멱등성 고려 대상이 아니다.)
• PUT: 멱등하다. 여러 번 요청해도 최종 상태는 항상 같다 (해당 URI의 리소스가 요청 내용으로 대체된다).
• DELETE: 멱등하다. 여러 번 요청해도 최종적으로 리소스가 삭제된 상태는 같다 (이미 삭제된 상태에서 다시 삭제 요청을 보내도 오류가 발생하지 않거나 같은 결과를 나타낸다).
• POST: 멱등성을 보장하지 않는다. 동일한 POST 요청을 여러 번 보내면 새로운 리소스가 계속 생성될 수 있다 (예: 계좌 송금, 게시글 작성, 회원 가입 등).
• 멱등성은 요청 실패 시 재시도를 안전하게 할 수 있도록 해준다.
• 멱등하지 않은 요청은 중복으로 처리될 위험이 있으므로 재시도에 주의해야 한다.
• 서버의 복구 메커니즘 (예: 요청 실패 시 자동 재시도)에 활용된다.
• 리소스 조회 시 재요청과 데이터 변경: 재요청 중간에 리소스가 변경되는 것은 멱등성 판단 기준에 포함되지 않는다. 멱등성은 요청 자체의 반복적인 수행이 동일한 결과를 보장하는지에 대한 속성이다.

3. 캐시 가능성 (Cacheable)

• 응답 결과를 재사용 목적으로 저장 (캐싱)할 수 있는지 여부를 나타낸다.
• GET, HEAD, POST: 캐시가 가능하다.
• 일반적으로 GET, HEAD 메소드의 응답만 캐시로 활용하는 경우가 많다.
• 변경 가능성이 낮은 정적 자원 (HTML, CSS, IMAGE, JS 등)을 주로 캐싱하여 성능을 향상시킨다.

HTTP 상태 코드

HTTP 요청에 대한 처리 결과를 나타내는 응답 코드로, 응답 데이터와 함께 전송된다. Spring 프레임워크에서는 ResponseEntity 등을 사용하여 응답 메시지를 커스터마이징하여 더 의미 있는 정보를 제공하기도 한다.

HTTP 응답 메시지 구조

HTTP 상태 코드 분류

• 1xx (정보): 요청이 수신되어 처리 중인 상태 (거의 사용되지 않음).
• 2xx (성공): 요청이 정상적으로 처리 완료된 상태.
  • 200 OK: 요청 성공 (가장 일반적인 성공 응답).
  • 201 Created: 새로운 리소스가 성공적으로 생성됨.
  • 202 Accepted: 요청이 접수되었으나 아직 처리가 완료되지 않음 (주로 배치 처리 등에 사용).
  • 204 No Content: 요청은 성공했으나 응답 데이터가 없음 (예: 데이터 저장/삭제 후 별도의 응답이 필요 없는 경우).
• 3xx (리다이렉션): 요청을 완료하기 위해 클라이언트의 추가적인 동작이 필요한 상태. Location HTTP 헤더와 함께 리다이렉션할 URI를 제공한다.(어떠한 방식으로라도 변경된 관계를 서버에 남겨놔야한다)
  • 영구 리다이렉션 (Permanent Redirection): URL이 영구적으로 변경된 경우. 기존 URL은 더 이상 사용하지 않도록 안내한다.
    • 301 Moved Permanently: 요청 메소드가 GET으로 변경될 수 있으며, 응답 본문이 제거될 수 있다.
    • 308 Permanent Redirect: 리다이렉트 시 요청 메소드와 본문이 유지된다.
  • 일시 리다이렉션 (Temporary Redirection): URI가 일시적으로 변경된 경우 (예: 게시글 작성 후 목록 페이지 이동 - PRG 패턴).
    • 302 Found: 요청 메소드가 GET으로 변경될 수 있다 (모호하여 303, 307 등장).
    • 303 See Other: 요청 메소드가 반드시 GET으로 변경된다.
    • 307 Temporary Redirect: 리다이렉트 시 요청 메소드와 본문이 유지된다.
  • 기타 리다이렉션: 캐시 제어 관련
    • 304 Not Modified: 캐시 목적으로 사용된다. 리소스가 수정되지 않았음을 나타내며, 클라이언트에게 캐시된 데이터를 사용하도록 지시한다. 응답에 본문이 없어야 한다.
• 4xx (클라이언트 에러): 클라이언트 측 오류로 인해 서버가 요청을 처리할 수 없는 상태. 동일한 요청을 재시도해도 실패한다.
  • 400 Bad Request: 클라이언트의 요청 구문이 잘못되었거나 유효하지 않음 (예: 요청 메소드 불일치, API 스펙 오류 등).
  • 401 Unauthorized: 요청된 리소스에 대한 인증 (Authentication)이 필요하다. WWW-Authenticate 헤더를 통해 인증 방법을 제시한다 (예: 로그인 필요).
  • 403 Forbidden: 서버가 요청을 이해했지만, 클라이언트에게 해당 리소스에 대한 접근 권한이 없음 (인가 - Authorization 문제).
  • 404 Not Found: 요청한 리소스가 서버에 존재하지 않음 (리소스를 숨기는 목적으로 사용되기도 함).
• 5xx (서버 에러): 서버 오류로 인해 요청을 처리할 수 없는 상태. 재시도하면 성공할 수도 있다. 서버 측 문제이므로 발생하지 않도록 하는 것이 최선이다.
  • 500 Internal Server Error: 서버 내부 오류 (대부분의 서버 오류를 포괄적으로 나타냄).
  • 503 Service Unavailable: 서버가 일시적으로 서비스를 제공할 수 없는 상태 (Retry-After 헤더를 사용하여 복구 예상 시간을 알릴 수 있다).

참고: 모든 상태 코드를 암기할 필요는 없으며, 100단위의 의미만 이해하고 필요한 경우 상세 코드를 찾아보는 것이 효율적이다. 상황에 맞는 적절한 응답 코드를 사용하는 것은 매우 중요하고 기본적인 API 설계 원칙이다.

HTTP API 설계

잘못된 HTTP API 설계 예시

게시글 생성/create/board
게시글 1개 조회/read/board/1
게시글 목록 조회/read/board-list
게시글 수정/update/board/1
게시글 삭제/delete/board/1

올바른 HTTP API 설계 방법

HTTP API는 리소스 식별을 중심으로 설계해야 한다. 위 예시에서 리소스는 "게시글"이다.

• URI에 리소스 명사는 복수 형태로 사용하는 것을 권장한다 (board → boards).
• URI에 동사를 사용하지 않는다. HTTP Method를 통해 수행할 행위를 명시한다.
• HTTP Method의 역할을 URL에 포함시키지 않는다 (/create/board 대신 POST /boards).

HTTP API 설계 예시

• 게시글 생성: POST /boards (성공 시 2xx, 실패 시 4xx 또는 5xx)
• 게시글 1개 조회: GET /boards/{id} (성공 시 2xx, 실패 시 4xx 또는 5xx)
• 게시글 목록 조회: GET /boards (성공 시 2xx, 실패 시 4xx 또는 5xx)
• 게시글 수정: PUT /boards/{id} 또는 PATCH /boards/{id} (성공 시 2xx, 실패 시 4xx 또는 5xx)
• 게시글 삭제: DELETE /boards/{id} (성공 시 2xx, 실패 시 4xx 또는 5xx)

핵심: HTTP API 설계 시 리소스를 명확히 식별하고, URI는 리소스 자체를 나타내도록 설계하며, HTTP Method를 통해 리소스에 대한 행위를 정의하는 것이 중요하다.

 

 

 

 

 

AI 음성 개요 생성