BoldHeaderBoldHeader

RESTful API의 상황별 응답코드

"RESTful API Response Codes"라는 주제는 웹 개발 및 API 설계에서 중요한 역할을 하는 핵심 주제 중 하나입니다. 웹 서비스와 애플리케이션은 데이터를 주고받기 위해 API를 사용하며, 이 API가 올바르게 동작하고 상태를 효과적으로 전달하기 위해서는 적절한 응답 코드를 사용하는 것이 중요합니다. 이러한 응답 코드는 클라이언트와 서버 간의 원활한 통신을 보장하고, 오류 처리와 문제 해결에 도움을 줍니다.

RESTful API는 HTTP 프로토콜을 기반으로 하며, 클라이언트의 요청에 대한 응답으로 HTTP 상태 코드를 반환합니다. 이 상태 코드는 요청의 결과를 나타내는 중요한 정보를 담고 있으며, 클라이언트에게 어떻게 행동해야 할지 안내합니다. 이 글에서는 RESTful API 응답 코드의 주요 카테고리와 각 코드가 무엇을 의미하는지 자세히 알아보겠습니다.

참조 : https://learn.microsoft.com/ko-kr/azure/architecture/best-practices/api-design

GET method

  • 200(OK) : 일반적인 정상 조회
  • 404(Not Found) : 리소스를 찾을 수 없는 경우
  • 204(No Content) : Response의 내용이 없는 경우 - 예를 들어 검색결과 없음, Empty Collection.

POST method

  • 201(Created) : 새로운 리소스 생성
    • 새 리소스의 URI는 응답의 Location 헤더에 포함됨(생성된 id값)
  • 200(OK): 새 리소스를 만들지는 않지만 일부 처리를 하는 경우. 작업 결과를 본문에 넣음
  • 204(No Content): 반환할 결과가 없는 경우
  • 400(Bad Request): 클라이언트가 잘못된 데이터를 요청한 경우. 본문에는 오류에 대한 추가정보 또는 자세한 정보를 포함한 URI 링크

PUT의 Http Status Code

  • 201(Created): 새 리소스를 만드는 경우
  • 200(OK) : 기존 리소스를 업데이트 할 경우
  • 204(No Content): 기존 리소스를 업데이트 할 경우
  • 409(Conflict): 기존 리소스를 업데이트 할 수 없는 경우

PATCH의 Http Status Code

  • 415(Unsupported Media Type): 지원되지 않는 형식

  • 400(Bad Request): 잘못된 형식

  • 409(Conflict): 형식은 맞지만 변경 내용을 적용할 수 없는 경우*

  • JSON Merge Patch( RFC 7396)

    • 필드 삭제 시에는 필드값에 null을 지정
    • null 값을 가질 수 있는 필드의 경우에는 Merge Patch가 적합하지 않음.(필드 삭제의 의미로 사용되므로)
    • Media Type : application/merge-patch+json

  • JSON Patch(RFC 6902)

    • 작업 결과로 적용할 변경 내용을 지정
    • Media Type : application/json-patch+json

DELETE의 Http Status Code

  • 204(No Content): 성공적으로 삭제 처리
  • 404(Not Found): 삭제할 리소스가 없는 경우

비동기 작업

비동기 작업으로 처리 작업이 완료되기 전에 클라이언트에게 응답을 보내는 경우

  • 202(Accepted): 요청은 수락되었지만 아직 완료되지 않음

클라이언트가 상태를 모니터링할 수 있도록 상태를 확인할 수 있는 엔드포인트 URI를 Location Header에 포함해야함

HTTP/1.1 202 Accepted
Location: /api/status/12345

클라이언트가 이 엔트포인트로 GET요청을 보내는 경우, 현재 상태가 포함되어야 함. 경우에 때라 예상 완료시간 또는 작업 취소 링크를 반환할 수 있음

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status":"In progress",
    "link": { "rel":"cancel", "method":"delete", "href":"/api/status/12345" }
}
  • 비동기 작업에서 새 리소스를 만드는 경우, 작업이 완료된 후 엔트포인트에서는 303(See Others) 반환하고, 응답의 Location 헤더에 새 리소스의 URI를 제공
HTTP/1.1 303 See Other
Location: /api/orders/12345