HTTP 상태 코드 for CRUD App

REST API 개발중에 응답에 필요한 상태코드를 결정하는 데에 난해함을 느껴서 내친김에 HTTP 상태코드에 대해 정리해보기로 했다. 참고할만한 use case를 찾던 중 해외 API 분석 플랫폼 Moesif에 작성된 좋은 블로그 글이 있어서 해당 글의 내용을 정리하려한다.

이 글은 Moesif Bolg에 게시된 Which HTTP Status Code to Use for Every CRUD App 의 내용을 바탕으로 작성되었습니다

API 설계에 있어서 클라이언트에게 올바른 응답을 보내주는 것은 중요하다. 클라이언트는 받은 응답 데이터만으로 자신의 요청이 어떻게 처리되었는지 문제가 발생했다면 어떤 이유로 발생했는지 명확하게 인식할 수 있어야한다. HTTP 명세는 클라이언트에게 응답할 때 사용할 수 있는 다양한 상태코드를 정의하고 있으며 이를 잘 활용하면 기본적인 코드(ex: 200 OK)만을 사용하며 그외 상태를 표시하기 위해 자체적인 응답 데이터를 남발하는 것을 피할 수 있다.

Status Classes

1. 1xx (100 - 199)
   정보 상태 코드로 HTTP 1.1에 도입되었으며, 일반적으로 클라이언트에게 요청의 헤더 부분 이 수신되었으며 서버가 클라이언트의 요청을 처
   리할 것임을 알려주는 데에 사용된다.

2. 2xx (200 - 299)
   성공 상태 코드로, 클라이언트에 요청이 성공적으로 수신, 이해, 수락되었음을 나타낸다. 요청이 비동기적으로 처리될 경우(202 Accepted), 해당 응답 코드는 요청이 유효성 검사 요건를 충족해서 서버가 요청을 처리하기 시작했음을 의미하며 요청이 최종적으로 성공적인 처리가 되었음을 의미하지는 않는다.

3. 3xx (300 - 399)
   리다이렉션 상태 코드로, 요청한 리소스가 클라이언트가 예상한 위치에서 더이상 사용될 수 없으며 새 위치로 이동하도록 지시한다.

4. 4xx (400 - 499)
   클라이언트 오류 상태 코드로, 클라이언트가 보낸 유효하지 않은 요청으로 인해 서버가 요청을 처리할 수 없음을 나타낸다. 여기에는 시간 초과, 잘못된 URI, 인증 누락 등 여러 원인이 있을 수 있다.

5. 5xx (500 - 599)
   서버 오류 상태 코드로 서버가 클라이언트 요청을 처리하는 데에 실패했으며 문제의 원인이 서버 측에 있음을 의미한다.

CRUD API를 위한 Status Codes

CREATE

주로 POST 요청을 통해 이루어지는 동작으로, REST API에서는 새로운 리소스나 액세스 토큰을 생성할 때 사용된다.

1. 200 OK
   클라이언트에게 요청 내용이 잘 처리되었음을 알리는 기본 상태 코드이다. 액세스 토큰 생성시 이에 액세스할 수 있는 리소스의 엔드포인트를 만들지 않기 때문에 해당 작업의 상태 코드로 200 OK를 사용하는 것이 적절하다.

2. 201 Created
   CREATE 작업에 가장 적합한 상태 코드로, 서버 측에 리소스가 생성되었음을 알리고 새로 생성된 리소스에 대한 엔드포인트를 명시한 Location 헤더와 함께 제공되어야 한다. 또한 응답 본문에는 리소스의 적절한 표현 또는 해당 리소스에 대한 하나 이상의 URL을 포함하는 것이 권장된다.

3. 202 Accepted
   비동기 처리에 자주 사용되는 상태 코드로, 클라이언트에게 요청이 유효하며 처리가 가까운 미래에 완료될 것임을 알린다. 응답 본문에는 완료된 리소스를 사용할 수 있는 시점에 대한 정보와 함께 완료된 리소스에 대한 URL 또는 리소스를 사용할 수 있는 시점을 클라이언트에게 알려주는 모니터링 엔드포인트에 대한 URL이 포함되어야 한다.

4. 303 See Other
   202 Accepted 와 유사하지만 Location 헤더 필드를 사용하여 생성된 리소스의 위치나 생성 프로세스의 상태를 확인할 수 있는 엔드포인트로 클라이언트를 리다이렉트 시킨다. 주로 POST 요청에 사용되며 클라이언트가 리다이렉션 URL로 GET 요청을 보내도록 한다.

READ

주로 GET 요청을 통해 이루어지는 동작으로, 리소스 표현Resource Representation을 가져오는 데에 사용된다. 비동기 처리 응답은 리소스가 아직 존재하지 않아서 생성해야하는 경우가 많기 때문에, READ 동작을 다룰 때 크게 중요하지 않으므로 다루지 않는다.

1. 200 OK
   대부분의 READ 작업은 조회 성공시 응답 본문에 조회 데이터와 함께 200 OK 로 응답한다.

2. 206 Partial Content
   이 코드는 조회하려는 데이터가 너무 커서 하나의 응답으로 전달할 수 없는 경우에 사용된다. 이 상태 코드는 주로 대용량 파일이나 멀티미디어 스트림을 다운로드할 때 유용하며, 클라이언트가 전체 리소스 대신 특정 범위의 데이터만을 요청할 수 있게 해준다. Range 헤더와 함께 사용되어 조회할 데이터의 특정 부분을 명시하여 요청할 수 있다.

3. 300 Multiple Choices
   이 코드는 요청된 리소스가 여러 가지 표현을 가지며 클라이언트가 그 중 하나를 선택해야 하는 경우에 사용된다.

4. 308 Permanent Redirect
   클라이언트가 리소스에 접근할 때 현재 URL을 더 이상 사용하지 않고 다른 URL을 사용하도록 지시한다. 하나의 리소스에 대한 여러 엔드포인트가 있지만 모든 엔드포인트에서 READ 를 구현하고 싶지 않을 때 유용하게 사용할 수 있다. 요청 메서드와 본문은 변하지 않는다.

5. 304 Not Modified
   200 처럼 사용되지만 본문이 없으며, 리소스가 변경되지 않아 클라이언트를 이전의 READ 가 캐시된 표현으로 리다이렉트시킬 때 사용된다.

6. 307 Temporary Redirect
   클라이언트가 요청한 리소스가 일시적으로 다른 위치에 있으며, 현재의 메서드와 본문을 유지한 채로 리다이렉트시킬 때 사용한다

UPDATE

PUT이나 PATCH 메서드를 통해 이루어지는 동작으로, 두 메서드의 차이는 UPDATE 를 위해 클라이언트가 서버에 전송하는 데이터의 양에 있다.

1. 200 OK
   대부분의 use-case에 적절한 상태 코드이다.

2. 204 No Content
   클라이언트에 데이터를 반환하지 않는 업데이트(예: 현재 편집한 문서를 저장하는 경우)에 적합한 상태 코드이다.

3. 202 Accepted
   UPDATE 가 비동기로 수행되는 경우 사용할 수 있으며 CREATE 에서와 마찬가지로 업데이트된 리소스에 액세스할 수 있는 URL 또는 업데이트가 성공했는지 확인할 수 있는 URL이 포함되어야 하며 UPDATE 에 걸리는 예상시간 또한 포함될 수 있다.

DELETE

DELETE 메서드를 통해 구현되는 동작이다.

1. 200 OK
   삭제된 리소스를 응답 본문에 포함시킬 경우 사용된다.

2. 204 No Content
   DELETE 에 가장 적합한 상태코드로, 트래픽을 줄이고 클라이언트에게 응답 본문 없이 단순히 삭제 작업이 완료되었음을 알리는 상태 코드이다.

3. 202 Accepted
   분산 시스템과 같이 DELETE 가 비동기로 처리되고 시간이 걸리는 경우, 클라이언트에 삭제 시점을 알려주는 정보 또는 URL과 함께 이 코드를 반환하는 것이 적절할 수 있다.

* Permission 관련 에러 코드

1. 401 Unauthorized
   요청된 리소스에 대한 유효한 인증 자격 증명이 없기 때문에 클라이언트의 요청이 완료되지 않았음을 나타낸다.

2. 403 Forbidden
   클라이언트가 리소스에 접근할 권한이 충분치 않음을 나타낸다.

3. 404 Not Found
   401 또는 403 에 해당하지만 서버에서 보안상의 이유로 리소스의 존재를 클라이언트에게 알리지 않으려고 할 경우 사용된다.