REST API 디자인 규칙 - 3장

3.1 HTTP/1.1

• REST API는 요청 메서드, 응답 코드, 메시지 헤더 등 HTTP 버전 1.1의 모든 측면을 수용한다.

3.2 요청 메서드

• REST API 리소스 모델에서 각 HTTP 메서드는 잘 정의된 고유한 의미가 있다.
• 규칙
  • GET 메서드나 POST 메서드를 사용하여 다른 요청 메서드를 처리해서는 안된다.
    • 원래 의미와 다르게 사용하지 마라.
  • GET 메서드는 리소스의 상태 표현을 얻는 데 사용해야 한다.
  • 응답 헤더를 가져올 때는 반드시 HEAD 메서드를 사용해야 한다.
  • PUT 메서드는 리소스를 삽입하거나 저장된 리소스를 갱신하는데 사용해야 한다.
    • 이미 스토어에 저장된 리소스를 갱신하거나 다른 것으로 대체하는 데도 사용한다.
  • PUT 메서드는 변경 가능한 리소스를 갱신하는 데 사용해야 한다.
  • POST 메서드는 컬렉션에 새로운 리소스를 만드는 데 사용해야 한다.
    • 요청 바디는 새로운 리소스를 위해 넘겨주는 정보 → 서버 소유 컬렉션에 추가
  • POST 메서드는 컨트롤러 실행하는 데 사용해야 한다.
    • 기능 지향적인 컨트롤러 리소스를 동작시킬 수 있다.
    • 컨트롤러 리소스는 유연성을 높이기 위해 투명도와 강건성을 조정해야 한다.
  • DELETE 메서드는 그 부모에서 리소스를 삭제하는 데 사용해야 한다.
    • 컬렉션이나 스토어인 부모에서 리소스를 완전히 제거.
    • DELETE 후 GET or HEAD 메소드 호출 시 404 상태로 끝남.
    • 삭제하는 것 이외에는 어떠한 동작에도 쓰이면 안됨.
      • 임시 삭제 등 특별한 컨트롤러 → POST 사용한다.
  • OPTIONS 메서드는 리소스의 사용 가능한 인터랙션을 기술한 메타데이터를 가져오는 데 사용해야 한다.
    • Allow 헤더에 포함된 리소스 메타데이터를 가져옴.

3.3 응답 상태 코드

• 범주
  • 1xx : 정보 → 전송 프로토콜 수준의 정보 교환
  • 2xx : 성공 → 클라 요청 성공
  • 3xx: 재전송 → 클라 요청을 완료하기 위해 추가 행동 필요.
  • 4xx: 클라 오류 → 클라 잘못된 요청
  • 5xx: 서버 오류 → 서버쪽 오류
• 규칙
  • 200 OK는 일반적인 성공 요청을 나타내는 데 사용해야 한다.
  • 200 OK는 응답 바디에 에러를 전송하는 데 사용해서는 안 된다.
  • 201 Created는 성공적으로 리소스를 생성했을 때 사용해야 한다.
    • POST를 이용하여 새로운 리소스를 컬렉션 생성 또는 스토어에 추가된 경우
    • 컨트롤러의 행동으로 새로운 리소스가 생겨났을 경우
  • 202 Accepted는 비동기 처리가 성공적으로 시작되었음을 알릴 때 사용해야 한다.
    • 클라의 유효한 요청이지만, 비동기 처리가 될 것이기 때문에 최종적으로 처리되기까지는 문제가 생길 수도 있다.
  • 204 No Content 응답 바디에 의도적으로 아무것도 포함되지 않을 때 사용한다.
    • 보통 PUT, POST, DELETE 요청에 대한 응답으로 이용한다.
    • 굳이 GET을 사용할 수 있는데 그 경우 요청된 리소스는 있지만 내려주지 않는다를 의미하는 정도로 이해하면 될 것 같다.
  • 301 Move Permanently는 리소스를 이동시켰을 때 사용한다.
  • 302 Found는 사용하지 않는다.
  • 303 See Other은 다른 URI를 참조하라고 알려줄 때 사용한다.
  • 304 Not Modified는 대역폭을 절약할 때 사용한다.
  • 307 Temporary Redirect는 클라이언트가 다른 URI로 요청을 다시 보내게 할때 사용한다.
  • 400 Bad Request는 일반적인 요청 실패에 사용해야 한다
    • 다른 적절한 4xx 오류 값이 없을 때 사용한다.
  • 401 Unauthorized 는 클라이언트 인증에 문제가 있을 때 사용한다.
    • 인증을 잘못하거나 아예 인증하지 못할 경우에 발생한다.
  • 403 Forbidden 는 인증 상태에 상관없이 액세스를 금지할 때 사용한다.
    • 클라 요청은 정상이지만 API가 요청에 응하지 않는 경우에 사용한다.
    • 클라 허용된 범위 외의 리소스에 접근하려고 할 때 사용한다.
  • 404 Not Found 는 요청에 해당하는 리소스가 없을 때 사용한다.
  • 405 Method Not Allowed는 HTTP 메서드가 지원되지 않을 때 사용해야 한다.
    • 허용되지 않은 메소드를 사용하려 할 때 사용한다.
  • 406 Not Acceptable 은 요청된 리소스 미디어 타입을 제공하지 못할 때 사용해야 한다.
    • 요청 헤더에 있는 미디어 타입 중 해당하는 것을 만들지 못할 때 발생한다.
  • 409 Conflict 는 리소스 상태에 위반되는 행위를 했을 때 사용해야 한다.
    • API 리소스가 불가능 또는 모순 상태가 될 수 있는 경우 사용한다.
  • 412 Precondition Failed는 조건부 연산을 지원할 때 사용한다.
    • 특정한 조건이 만족될 때만 요청이 수행되도록 한다.
  • 415 Unsupported Media Type 은 요청의 페이로드에 있는 미디어 타입이 처리되지 못했을 때 사용해야 한다.
  • 500 Internal Server Error는 API가 잘못 작동할 때 사용해야 한다.
    • 서버 오류 상황시 사용한다. (클라이언트 잘못으로 발생한 것이 아님.)