[Network] 4. HTTP 메소드, 상태 코드

API URL 설계 시 포인트

URL 설계 시 가장 중요한 것은 리소스 식별이다.

 

리소스란 ?

동작을 제외한 자원 그 자체를 리소스라한다. 회원 등록 시스템을 예로 들면, 회원을 등록하거나 수정 혹은 삭제하는 행위는 리소스가 아니다. 오직 회원이라는 개념만이 리소스라 할 수 있다.

 

리소스 기반의 회원 관리 URL 설계

동작은 HTTP 메소드로 구분한다. (Ex: GET, POST, PUT, PATCH, DELETE, ...)

• 회원 목록 조회 : GET /members
• 회원 조회 : GET /members/{id}
• 회원 등록 : POST /members
• 회원 수정 : PUT /members/{id}
• 회원 삭제 : DELETE /members/{id}

 

HTTP 메소드

GET

• 리소스 조회에 사용.
• 서버에 전달할 데이터는 query string을 통해 전달.
• 메시지 바디는 사용 가능하지만 지원되지 않는 곳이 많아 권장하지 않는다.

POST

• 메시지 바디를 통해 서버로 요청 데이터를 전달하면 해당 데이터를 처리한다.
• 주로 등록 혹은 프로세스 처리 등에 사용.
  • 리소스 등록 : 서버가 아직 식별하지 않은 새 리소스 생성(회원 등록)
  • 요청 데이터 처리 : 단순한 데이터 생성을 넘어 프로세스를 처리해야 하는 경우로, 꼭 새로운 리소스가 생성되지 않을 수도 있다.
• 다른 메소드로 해결하기 어려운 경우 POST를 사용하고는 한다.

PUT

• 리소스 대체의 목적으로 리소스가 있을 경우 대체, 없을 경우 생성.
• 특정 리소스를 식별하기에 POST와는 구별점을 가진다.

PATCH

• 리소스 부분 변경
• PUT과 비슷해 보이고 보내는 양식도 비슷하지만, 대치가 아닌 필요한 부분만 업데이트 하는 방식.

DELETE

• 리소스를 제거할 때 사용.
• 리소스 식별자를 DELETE로 보낼 경우 해당 리소스를 삭제한다.

 

HTTP 메소드의 속성

HTTP 메소드	RFC	요청에 Body가 있음	응답에 Body가 있음	안전	멱등	캐시가능
GET	RFC 7231	X	O	O	O	O
HEAD	RFC 7231	X	X	O	O	O
POST	RFC 7231	O	O	X	X	O
PUT	RFC 7231	O	O	X	O	X
DELETE	RFC 7231	X	O	X	O	X
CONNECT	RFC 7231	O	O	X	X	X
OPTIONS	RFC 7231	선택 사항	O	O	O	X
TRACE	RFC 7231	X	O	O	O	X
PATCH	RFC 5789	O	O	X	X	O

 

안전(Safe Methods)

• 호출해도 리소스가 변경되지 않는다.
• GET, OPTIONS, TRACE 등은 조회의 성격을 가지고 있기에 리소스를 변경하지 않고, 그렇기에 안전하다.
• 이 때, 안전의 범위는 해당 리소스에만 해당되고 그 외적인 요소는 고려하지 않는다.
  • 리소스 호출시마다 로그가 남아도 이는 리소스에 대한 영향은 아니기 때문에 고려하지 않는다.

멱등(Idempotent Methods)

• 메소드를 반복해서 호출하더라도 결과가 동일해야 한다.
• GET, PUT, DELETE 같은 경우 여러번 호출하더라도 GET은 같은 데이터를 조회, PUT은 대치된 값을 반환하기에 동일, DELETE도 결과를 삭제하기에 같은 요청하더라도 삭제된 내용이 복구도지는 않기에 멱등성을 성립한다.
• POST의 경우 회원 등록을 두 번하거나 주문을 두 번할 경우 에러가 발생하거나 주문 중복이 생길 수 있기에 멱등성이 성립하지 않는다.

캐시 가능(Cacheable Methods)

• 표에서는 GET, HEAD, POST, PATCH가 캐시가능이라 되어있지만, 실제로는 GET, HEAD 정도만 캐시로 사용된다.
• POST, PATCH는 본문 내용(Message Body)까지 캐시 키로 고려해야 하는데 구현이 쉽지 않다.

 

HTTP 메소드 활용

클라이언트에서 서버로 데이터 전달 방식

• 쿼리 파라미터를 통한 데이터 전송 : GET에서 많이 사용하고 정렬필터나 검색기능에서 많이 사용.
• 메시지 바디를 통한 데이터 전송 : POST, PUT, PATCH 등 회원 가입, 수정, 상품 주문과 같이 리소스를 등록 및 수정하는데 사용

 

HTTP API 설계 개념

컬렉션

• POST 기반 등록으로 리소스 등록의 주체를 서버에서 담당한다.
• 회원관리 API 같은 예시가 대표적이다.
• 회원 등록시 회원의 식별 코드는 서버측에서 생성 및 관리한다.

스토어

• PUT 기반으로 클라이언트가 자원의 URL를 알고 관리의 주체가 된다.
• 파일 등록 시스템 API 같은 경우가 대표적.
• 파일 등록시 파일 이름은 클라이언트가 알고 있다.

문서

• 단일 개념으로 파일하나, 객체 인스턴스, 데이터베이스의 ROW 등.

컨트롤러, 컨트롤 URI

• 문서, 컬렉션, 스토어 등으로 해결하기 어려운 추가 프로세스 실행에 사용됨.
• 동사를 사용하며 리소스의 행위를 사용한다.
• HTML FORM 기반 설계의 경우 GET, POST만 사용할 수 있기에 PUT, PATCH, DELETE 와 같은 행위에 대해서는 컨트롤 URI로 설계한다.

 

HTTP 상태 코드

상태 코드

HTTP API에 대해 클라이언트가 요청을 보내면 서버측에선 응답 메시지를 돌려주는데, 이 상태코드를 통해서 서버에서 어떻게 처리되었는지 추측할 수 있다.

• 1xx(informational) : 요청이 수신되어 처리중. 거의 사용하지 않음
• 2xx(Successful) : 요청이 정상적으로 처리됨.
  • 200(OK) 
    • GET과 같은 조회 요청에 성공적으로 응답하는 경우
  • 201(Created)
    • POST와 같은 생성요청으로 리소스가 생성이 정상적으로 된 경우에 해당
    • 응답 메시지(헤더)에는 생성된 리소스 식별자가 Location 필드에 추가되어 응답된다.
  • 202(Accepted)
    • 요청은 서버에서 받았으나 아직 처리가 되지 않은 경우
    • Ex: 배치 프로세스 등이 이에 해당한다.
  • 204(No Content)
    • 서버에서 요청은 성공적으로 수행했으나 응답 시 메시지 바디에 담을 데이터가 없는 경우에 해당.
• 3xx(Redirection) : 요청을 완료하기 위해 추가 행동이 필요 (리다이렉션)
  • 응답메시지 헤더에 Location 필드가 있는 경우 해당 위치로 자동으로 이동.(리다이렉트)
  • 영구 리다이렉션 : 특정 리소스의 URI가 영구적으로 이동
    • 301(Moved Permanently)
      • 리다이렉트시 요청 메소드가 GET으로 변한다.
      • 본문이 변경될 수 있다. => 과거 스펙에서는 변경이 안되다가 최근 바뀜.
    • 308(Permanent Redirect)
      • 301 상태코드와 기능은 동일하다.
      • 응답 메시지 본문과 요청 메소드가 유지.
  • 일시 리다이렉션 : 리소스의 URI가 일시적으로 변경.
    • 302(Found)
      • 리다이렉트시 요청 메소드가 GET으로 변함.
    • 307(Temporary Redirect)
      • 302와 기능은 같음
      • 응답 메시지의 본문과 요청 메소드가 유지.
    • 303(See Other)
      • 302와 기능은 같다.
      • 리다이렉트시 요청 메소드가 GET으로 변함.
    • 304(Not Modified)
      • 캐시를 목적으로 사용
      • 클라이언트에 리소스가 수정되지 않았음을 알림.
      • 304 응답은 응답에 메시지 바디를 사용하면 안됨.
      • 조건부 GET, HEAD 요청시 사용
• 4xx(Client Error) : 클라이언트에서 잘못된 스펙으로 데이터를 보냈거나 인증, 인가가 만족되지 않아 서버에서 요청을 수행할 수 없다.
  • 400(Bad Request)
    • 클라이언트가 보내는 포맷이나 데이터에 문제가 있을 경우 발생
  • 401(Unauthorized)
    • 인증(Authentication)이 되지 않은 클라이언트에서 접근시 응답하는 상태코드.
  • 403(Forbidden)
    • 인증자격은 있지만, 해당 리소스에 접근할 권한이 없는 경우 응답하는 상태코드
    • Ex : 일반 회원이 관리자 페이지에 접근하려는 경우
  • 404(Not Found)
    • 요청 리소스를 찾을 수 없을 때 발생.
• 5xx(Server Error) : 서버에서 에러가 발생하여 요청을 정상 처리할 수 없는 경우
  • 500(Internal Server Error)
    • 서버 내부 문제로 오류가 발생
    • 서버측의 로직에서 발생하는 대다수의 예외나 에러는 모두 500 오류를 낸다.
    • 비즈니스 로직과 같이 시스템이 아닌 로직상 문제가 발생할 때 500 코드를 반환해서는 안된다.
  • 503(Service Unavailable)
    • 서버에 트래픽문제 혹은 점검으로 잠시 요청을 처리할 수 없는 경우 응답으로 사용된다.
    • Retry-After 헤더 필드로 얼마 뒤 복구되는지 보낼 순 있지만, 예측 불가능한 경우가 대부분이기에 잘 사용하지 않는다.

---

출처

[요약] 모든 개발자를 위한 HTTP 웹 기본 지식