[TIL] HTTP 상태 코드 설계

1. 주제 선택

팀원들과 프로젝트 S.A 설계를 완료한 후, 설계가 적합한지 확인하기 위해 튜터님께 피드백을 받았다. 이 과정에서 API 설계의 응답(response) 부분을 성공과 실패로 나눠 상태코드로 표현한 부분에 대해 긍정적인 평가를 받았고, 동시에 에러 상태를 조금 더 구체화하면 좋겠다는 제안과 함께 HTTP 상태코드 설계와 RESTful 여부에 대한 논의가 이루어졌다.

피드백 후, 프로젝트 마감 기한이 짧아 팀원들과 깊이 논의할 시간이 충분하지 않아 혼자 고민해보고 정리하고자 이 주제를 선택하게 되었다.

 

2. 고민한 내용

• 왜 RESTful한 상태 코드를 사용해야 하는가?
• RESTful하지 않은 설계는 어떤 상황에서 사용하는가?
• 상태코드를 설계할 때 클라이언트를 고려한 방식은 어떤 것인가?
• 만약 RESTful한 상태코드가 아닌 상황에 적절한 상태코드를 프로젝트에 적용해본다면 어떤 상태코드가 사용될까?

 

3. 공부한 내용

*RESTful 상태 코드 설계

• 정의
  • REST(Representational State Transfer) 아키텍쳐 스타일을 따르며, HTTP 표준 상태 코드와 메서드(GET, POST, PUT, DELETE 등)를 정확히 활용하는 설계 방식
• 특징
  • HTTP 상태 코드를 표준적으로 사용(200,201,404,500 등)
  • URI를 리소스 중심으로 설계(/users/1)
  • 클라이언트와 서버 간의 명확한 의사소통 가능
• 장점
  1. 일관성
     • HTTP 표준을 준수하기 때문에 클라이언트와 서버 간의 의사소통이 명확하다.
     • 상태 코드를 보고 요청이 성공했는지, 클라이언트의 실수인지, 서버 문제인지 빠르게 파악할 수 있다.
  2. 확장성
     • RESTful 설계를 기반으로 API를 확장하거나 새로운 기능을 추가할 때도 기존 설계를 재사용하기 쉽다.
     • API 문서화가 간단해지고, 유지 보수가 용이하다.
  3. 표준화
     • 개발자 간에 암묵적인 합의가 있기 때문에 상태 코드의 의미를 따로 설명할 필요가 없다.
     • 다양한 Tool(postman, http클라이언드)에서 RESTful 상태 코드를 예상한 동작과 함께 처리한다.
• 단점
  1. 구체적인 표현의 제한
     • 상태 코드만으로 비즈니스 로직에서 발생한 예외를 모두 표현하기 어렵다.
       • 예를들면 자주쓰이는 400 Bad Request가 다양한 오류를 표현하기 때문에 클라이언트가 특정 오류를 구분하기 어렵다.
     • 클라이언트가 다양한 상태 코드를 올바르게 이해하고 처리해야하기 때문에 번거로울 수 있다.
  2. 복잡성
     • 간단한 프로젝트가 클라이언트-서버 간의 단순 통신에서는 오히려 복잡할 수 있다.
• RESTful 상태코드 설계가 유리한 경우
  • 다수의 클라이언트가 API를 사용하며 표준화된 설계를 기대할 때
  • API 문서화와 자동화 도구를 활용할 때
  • 개발자 경험을 쌓거나 팀 간 협업이 활발한 환경일 때

*비 RESTful 상태 코드 설계

• 정의
  • HTTP 상태 코드를 반드시 RESTful 방식으로 사용하지 않고, 프로젝트나 클라이언트의 요구에 맞게 유연하게 설계하는 방식
• 특징
  • 상태 코드를 다양하게 사용하거나 단일화 가능
  • URI 설계가 반드시 리소스 중심이 아니어도 됨
  • 오류와 결과를 상태코드보다는 응답 메시지에 의존
•  장점
  1. 유연성
     • 프로젝트의 특성에 맞게 상태코드를 정의하고 사용할 수 있다.
     • 클라이언트가 이해하기 쉽도록 특정 상태코드 대신 항상 동일한 코드
  2. 클라이언트 처리 단순화
     • 모든 요청에 대해 동일한 상태 코드를 사용하고, 실제 오류 상황은 응답 메시지 형태로 전달하면 일관된 방식으로 클라이언트에서 처리할 수 있다.
  3. 오류 처리
     • HTTP 표준 상태 코드로는 표현하기 어려운 복잡한 비즈니스 규칙을 응답 메시지로 쉽게 표현할 수 있다.
• 단점
  1. 표준성 부족
     • 클라이언트가 HTTP 상태 코드에 익숙한 경우, RESTful하지 않은 설계는 혼란을 줄 수 있음
     • HTTP 표준에 익숙한 API 클라이언트나 개발자에게는 비RESTful 설계가 직관적이지 않게 느껴질 수 있음
  2. 문서화 및 협업 불편
     • 상태 코드가 아닌 응답 메시지에 의존하면 모든 에러 코드와 메시지를 문서화하고 클라이언트와 공유해야함
     • 새로운 클라이언트 개발자가 왔을 경우 학습하는데 시간이 오래 걸림
• 비RESTful 설계가 유리한 경우
  • 프로젝트 규모가 작고, 상태 코드를 유연하게 처리하는 것이 더 중요할 때
  • 비즈니스 로직의 세분화된 결과를 클라이언트에게 명확히 전달하는 것이 중요한 경우
  • 클라이언트와 서버 간의 통신 방식이 단순하고, 클라이언트가 상태 코드에 의존하지 않을 때

*상태 코드 선택의 기준

1. 성공 여부
   • 요청이 성공적으로 처리되었는가?
     • 성공 : 2xx
     • 실패 : 4xx , 5xx
2. 요청의 의도
   • 클라이언트가 무엇을 요청했는가?
     • 데이터 조회(GET) : 200, 204
     • 데이터 생성(POST) : 201
     • 데이터 수정(PUT, PATCH) : 200, 204, 404
     • 데이터 삭제(DELETE) : 200, 204, 404
3. 문제의 원인
   • 요청에 실패했을 때, 문제의 원인이 클라이언트인가? 서버인가?
     • 클라이언트 : 4xx
     • 서버 : 5xx
4. 상태코드의 의미 전달
   • 이 상태코드가 클라이언트에게 상황을 명확히 전달할 수 있는가?

*현재 진행중인 아웃소싱 프로젝트에 RESTful 하지 않지만 적절한 상태코드를 적용

(생각만 하고 실제 프로젝트에는 구현하지 않을 예정)

• 성공적인 응답(2xx)
  • 200 : 일반 성공
    • 가게 리스트 조회 성공
  • 201 : 리소스 생성 성공
    • 회원가입 성공, 주문 생성 성공
  • 202 : 요청이 접수되었으나 처리 중
    • 배달 요청 중(비동기 요청이 필요한 작업)
  • 204 : 컨텐츠가 존재하지 않음
    • 가게에 등록된 리뷰가 없음
• 클라이언트 에러(4xx)
  • 400 : 잘못된 요청
    • 입력값 검증 실패, 요청 파라미터 누락
  • 401 : 인증 실패
    • 로그인 필요, 세션 만료
  • 403 : 권한 없음
    • 사장님 권한 없이 가게 생성 요청
  • 404 : 리소스 없음
    • 요청한 가게, 메뉴, 주문을 찾을 수 없음
  • 409 : 중복
    • 이미 존재하는 이메일
  • 422 : 처리 불가능한 엔티티(Unprocessable Entity)
    • 최소 주문 금액 부족(비즈니스 규칙 위반)
• 서버 에러(5xx)
  • 500 : 일반적인 서버 에러 - 예기치 못한 예외 발생
  • 502 : Bad Gateway - 외부 시스템 연결 문제
  • 503 : 서비스 불가 - 시스템 점검 중

 

4. 배운 점

• 상태 코드의 역할
  • HTTP 상태 코드는 단순히 성공/실패를 나타내는 것이 아니라, 요청/응답의 맥락과 책임(클라이언트/서버)을 전달하는 수단
• RESTful 설계는 항상 최선인가?
  • 표준 준수가 중요한 대규모 프로젝트에서는 RESTful 설계가 유리함
  • 협업과 확장성 측면에서도 RESTful 상태코드를 사용하는 것이 좋지만, 상황에 따라 더 유연한 설계가 필요할 수 있음
  • 작은 프로젝트나 상태 코드 학습 부담을 줄이고 싶을 때는 비RESTful 설계가 클라이언트 중심적일 수 있음
  • 프로젝트 규모가 작고, 상태 코드를 유연하게 처리하는 것이 더 중요할 때에도 비RESTful 설계가 유리할 수 있음
• 절충안
  • 상태코드는 RESTful하게 설계하면서 추가 정보를 응답 메시지에 포함하여 클라이언트가 쉽게 이해할 수 있도록 함
  • 비즈니스 로직의 오류는 JSON 메시지로 세분화

5. 결론

RESTful 상태 코드 설계와 아닌 설계 모두 장단점이 존재하며, 프로젝트와 팀의 특성에 맞는 방식을 선택해야 하며, 최적의 설계는 클라이언트가 오류 상황을 명확히 이해하고 대응할 수 있도록 RESTful 상태 코드와 명확한 응답 메시지를 조합해야한다.

 

HTTP 상태 코드는 단순히 성공/실패를 전달하는 도구로 사용되야하는 것이 아니라, 책임 분리와 의사소통을 위한 수단으로 사용되야하며, 클라이언트와 서버 간 더 명확한 의사소통을 제공하는 것이 중요하다.

 

이 고민을 통해 상태 코드 설계와 응답 메시지의 중요성을 다시 한번 돌아보고 깨닫게 되었고, 프로젝트를 할 때 클라이언트의 관점에서 한번 더 생각해야된다는 것을 학습하였다.