TOC
들어가며
최근에 저희 팀 백엔드 개발자님(이하 K님)의 API 설계 설명을 듣는 과정에서 API 응답의 HTTP 상태 코드에 대한 입장이 달랐던 부분이 있었어요.
의견 1: 오류에도 200 OK 상태를 사용
BE : "제어 가능한 오류는 모두 200 OK로 내려가게 했어요."
내부 응답 바디에서 errorCode로 구분하는 방식입니다. 예를 들어 이런 거죠.
HTTP/1.1 200 OK
Content-Type: application/json
{
"errorCode": 4020, (유저가 존재하지 않음을 의미하는 오류 코드)
"message": "유저가 존재하지 않습니다."
}
의견 2: 오류에는 400번대 상태 코드를 사용
FE : "사용자 오류에는 400번대, 서버 오류에는 500번대 상태 코드를 사용하는 게 맞지 않나요?"
저는 지금까지 프런트엔드 개발을 할 때 웹 표준을 기준으로 의사결정을 해왔어요. 네트워크 통신도 마찬가지로 웹 표준을 기준으로 방향을 결정하고자 했고요. 저는 이런 구조를 생각했습니다.
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errorCode": 4020, (유저가 존재하지 않음을 의미하는 오류 코드)
"message": "유저가 존재하지 않습니다."
}
K님의 이야기를 들었을 때 이런 생각이 들었습니다.
- "HTTP 표준에는 이미
401 Unauthorized같은 상태 코드가 있는데, 왜 200을 써야 하지?" - "이렇게 하면 브라우저 개발자 도구에서 에러가 아닌 것처럼 보이는데, 디버깅하기 더 어렵지 않을까?"
웹 표준을 왜, 얼마나 엄수해야 할까?
그런데 이 논의는 이미 백엔드의 응답 구조가 잡힌 뒤, Swagger를 통해 설명해주시는 상황이었기에, 웹 표준에 다시 맞추기엔 수정이 많이 필요한 상황이더라고요.
곰곰히 생각해보니 이미 구성된 서버 코드를 변경하는 추가 공수를 감수하면서까지 웹 표준을 위해 힘써야 하는가? 하는 생각이 들었어요. 어쩌면 그저 나의 가치관, 혹은 아집이 아닐까? 저 역시 웹 표준을 왜 지켜야 하는지 저를 포함한 모두가 납득이 되면 좋겠다고 생각했어요.
그래서 이번 포스트는 웹 표준을 왜 지켜야 하는지, 그리고 얼마나 엄수해야 하는지 알아보고자 합니다. 웹 표준은 단지 규칙일까요, 아니면 그 이상의 의미가 있을까요?
조사 전의 저의 수준
조사 전 웹 표준을 지켜야 한다는 저의 근거들을 간단히 소개할게요.
- 누군가 팀에 합류하더라도 표준을 준수하면 이견 없이 적응할 수 있을 것이다. 공식의 힘.
- 웹 표준은 말 그대로 표준이므로 상용 서비스(Sentry 등)에서도 표준에 맞게 설계되어 있을 것이다.
- 웹 표준은 웹 성능과 사용자 경험, 접근성 등을 높이기 위함이므로 웹 표준을 지키면 서비스의 품질로 이어질 것이다.
과연 제가 잘 생각하고 있었는지, 아니면 모르고 있던 부분이 있는지 더 파헤쳐 보겠습니다.
웹 표준에 대하여
웹 표준은 뭘까?
먼저 웹 표준이 무엇인지 알아볼게요. 웹 표준은 여러 국제 표준 기구가 정한 규칙으로서 웹이 작동하는 방식입니다. (출처: MDN - Web Standards)
- 표준화 단체인 W3C가 권고한 표준안에 따라 웹사이트를 작성할 때 이용하는 기술(HTML, CSS, JS 등)의 규정이 담겨 있다.
- 어떤 운영체제나 브라우저를 사용하더라도 웹페이지가 동일하게 보이고 정상 작동해야 한다.
웹 표준을 정하는 기구
다음은 MDN에 정리된 웹사이트와 네트워크 시스템이 준수해야 하는 표준입니다.
- IETF (Internet Engineering Task Force): URI, HTTP, MIME의 설정과 사용 등에 관한 인터넷 표준(STD)
- W3C: 마크업 언어의 명세(예, HTML), 스타일 정의(예, CSS), DOM, 접근성
- IANA (Internet Assigned Numbers Authority): 이름과 숫자 레지스트리
- Ecma Intl.: JavaScript로 잘 알려진 스크립팅 표준
- ISO (International Organization for Standardization): 문자 인코딩, 웹사이트 관리, 사용자 인터페이스 디자인 등 다양한 면을 다루는 표준
웹 표준을 왜 지켜야 할까?
웹 표준은 단순히 정해진 규칙을 넘어서, 시스템 간의 통합성과 일관성을 보장하기 위한 국제적 합의입니다.
웹 표준을 따르는 것은 개발자 사이의 약속이자, 시스템 간의 호환성을 유지하는 기본 조건입니다. 이를 무시하면 단기적으로는 편할 수 있지만, 장기적으로 유지보수, 디버깅, 시스템 확장에 큰 장애물이 됩니다.
웹 표준은 장기적으로 왜 중요할까?
- 현재 전 인류의 절반이상이 인터넷을 사용하고 있으며 앞으로도 증가할 것이다.
- 웹 표준이 없던 밀레니엄 전후에는 브라우저 간의 차이가 극심해서 사실상 N개의 사이트를 만들어야 했다.
- 지금과 같이 표준이 있다면, 하나의 사이트만 유지해도 되고 보다 더 정보의 질과 비즈니스에 집중할 수 있다.
웹 표준이 왜 좋은 걸까?
출처: 갓대희의 작은공간:티스토리
유지보수
- 개발 및 운영의 효율성 제고
- 소스의 통일화로 수정 및 운영관리 용이
- 오래된 브라우저에서도 컨텐츠가 적절하게 표시
- 브라우저간 호환성과 운용성 확보
접근성
- 다양한 브라우저, 휴대폰 PDA, 장애인 지원용 프로그램에서도 대응 가능
- 사용자 접근성 향상 : 장애인, 고령자 등을 포함한 사용자층 확대 가능
- 스크린리더기 등 보조공학 기기 사용자들에게 보다 정확한 정보 제공 지원
성능
- 서버 부담의 감소
- 논리적이고 효율적으로 작성된 웹 문서
- 코드의 양(파일 크기) 감소
- 서버 부담의 감소
- 페이지 로딩 속도 향상
- CSS와 HTML이 분리
- 유지보수에 들어가는 시간 단축
- 불필요한 마크업 최소화
- 페이지 로딩속도가 향상
- 검색봇을 통한 효율적 노출과 같은 검색엔진 최적화 가능
웹 표준 준수의 결론
이런 결론에 도달했습니다.
- 웹 표준은 다양한 장점을 가지고 있습니다.
- 웹 표준은 작게는 협업, 넓게는 개발 생태계와 개발 문화에 대한 존중입니다.
- 웹 표준은 미래를 위한 투자이자, 약속입니다.
- 웹 표준은 이러한 이유로 중요하고, 또 지켜야 합니다.
웹 표준을 왜 지켜야 하는지에 대해 스스로 설득이 되었습니다.
HTTP 상태 코드에 대하여
오늘의 웹 표준 준수를 다루는 주요한 사건은 HTTP 상태 코드로부터 시작되었으니, HTTP 상태 코드를 웹 표준 관점에서 알아보겠습니다.
HTTP 상태 코드는 뭘까?
HTTP 상태 코드는 단순히 숫자는 아닙니다. 클라이언트가 서버의 응답을 어떻게 해석해야 하는지를 알려주는 신호예요. HTTP 상태 코드는 클라이언트와 서버 간의 통신을 명확하게 정의함으로써, 수많은 브라우저, 프록시 서버, API 클라이언트 도구들이 예측 가능한 방식으로 동작할 수 있도록 돕습니다.
MDN의 HTTP 상태 코드 문서에는 HTTP 상태 코드별로 어떤 의미를 가지는지 잘 정리되어 있습니다.
HTTP 상태 코드의 목적
- 클라이언트가 요청한 결과를 명확하게 표현한다.
- 중간 프록시나 캐시 서버가 응답을 적절히 처리할 수 있도록 돕는다.
- 프론트엔드 개발자가 예외 처리를 직관적으로 구성할 수 있게 한다.
- 모니터링 시스템이 이상 징후를 빠르게 감지하도록 돕는다.
정확히는 마지막 두 요소 때문에 네트워크 표준 상태 코드로 응답을 받고자 했습니다.
예시: 로그인 실패의 경우
200 OK: 요청은 성공적으로 처리되었고, 오류가 없다. →로그인 성공401 Unauthorized: 인증이 필요한 요청이지만, 인증 정보가 누락되었거나 유효하지 않다. →로그인 실패403 Forbidden: 인증은 되었지만, 해당 리소스에 접근 권한이 없다. →접근 제한
이처럼 HTTP 상태 코드를 올바르게 사용하는 것은 통신의 문맥을 명확히 하며, API의 신뢰성과 해석 가능성을 높이는 데 중요한 역할을 합니다.
그럼에도 200 OK를 사용하는 경우
BE : "카카오도 로그인 실패 시에 200을 주네요?"
웹 표준에 대한 정답을 찾기 전에 빅테크 기업들은 어떻게 하는지 알아보고자 했습니다. 알아보니 카카오 로그인에서는 실패 시에 200을 주더라고요. 처음에 K님께서 제안하신 방식과 같습니다.
경계는 모호하지만, 웹 표준을 준수해 401 Unauthorized로 응답을 주어도 좋았을 겁니다. 카카오만 특이한 건 아닙니다. 카카오 외에도 많은 대형 서비스에서 모든 API 응답을 200 OK로 통일하는 전략을 채택하기도 합니다.
왜 웹 표준을 무시하고 200 OK 방식으로 한 걸까요? 그 이유는 기술적인 편의성과 운영 효율 때문입니다.
1. 일관된 에러 처리 구조
- 모든 API 응답을 통일된 JSON 구조로 설계하면 프론트엔드에서 일괄적으로 에러 핸들링하기가 수월합니다.
- 예를 들어, 모든 응답을
response.errorCode와response.message를 기준으로 처리할 수 있습니다.
2. 모바일 및 SPA 환경에서의 유연함
- 모바일 앱이나 싱글 페이지 애플리케이션(SPA)에서는 다양한 네트워크 상황에서 빠르게 응답을 처리해야 합니다.
- 그래서 HTTP 상태 코드보다 응답 바디의 구조에 기반한 처리가 더 유리하다는 주장이 있습니다.
3. 모니터링 시스템과의 충돌 방지
- 일부 서버/프록시 환경에서는 4xx 또는 5xx 응답이 에러 로그로 기록되거나 알림이 발생하는 구조를 갖고 있습니다.
- 운영상 불필요한 알람을 줄이기 위해 200 OK를 사용하여 우회하는 전략을 취하기도 합니다.
마치며
웹 표준을 지키기로 결정하다
처음 의견이 갈린 것처럼, 개발 시장의 상황과 웹 표준의 관점에서도 완전한 정석은 없었습니다. 즉, 양쪽을 모두 선택할 수 있었습니다. 그렇다면 저희는 어떤 선택을 했을까요?
네, 웹 표준을 준수하는 방향으로 합의가 되었습니다. 여기에는 웹 표준 외의 개발적인 배경이 있었습니다.
에러에 데이터를 담을 수 있다
처음에는 K님께서 400번대 상태 코드로 응답을 내리게 되면, 이전의 json 응답 데이터 구조를 유지할 수 없다고 하셨습니다. 그렇다면 프런트엔드 입장에서는 에러의 무의미한 데이터 덩어리를 받게 되는 거고, 디테일한 서버의 오류 상태를 알 수 없는 상황이었어요.
그런데 저는 이렇게 응답을 받을 수 있다는 사실을 알고 있었습니다.
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errorCode": 4020, (유저가 존재하지 않음을 의미하는 오류 코드)
"message": "유저가 존재하지 않습니다."
}
그래서 다시 한 번 확인을 부탁드렸고, K님은 조사 후에 데이터를 오류 응답에 넣어 보낼 수 있다고 내용을 정정해주셨습니다.
생각보다 쉽게 바뀌네요
처음에 우려하던 것처럼 백엔드 코드가 너무 많은 구조의 변경이 생긴다면 웹 표준보다는 현행을 유지하려 했습니다. 표준이 좋다 하지만 너무 과하면 독이 되고, 또한 200 OK의 방법론이 완전히 사용이 금지된 것도 아니니까요.
그런데 저와 웹 표준에 대한 논의를 마친 K님께서 자리에서 뚝딱뚝딱 하시더니, HTTP 상태 코드를 변경해서 응답을 내리는 방법을 빠르게 찾아주셨습니다.
저의 생각
협업에서 이성만큼 중요한 감성
논의가 언쟁이 되지 않도록 조심하기
K님의 적극적인 자세와 수용력으로, 기존의 방식에서 웹 표준을 준수하는 방향으로 변경할 수 있었습니다. 저는 그런데 사실 감정적인 부분도 걱정이 됐어요. 성능? 유지보수성? 물론 필요하고 좋습니다. 하지만 이러한 쟁점들을 하나하나 부딪히고 조율해야 한다면 감정적으로 지칠 수도 있겠다는 생각이 들었어요. 저는 이런 기술적 딥다이브가 즐겁지만, 상대는 아닐 수도 있으니까요. 그래서 적은 논의와 객관적인 근거로 빠르게 결론을 내려고 했던 것도 있습니다.
이성적 교류에 앞서 감정적 교류가 우선된다
하지만 다행히도 K님께서도 지금까지 습관처럼 개발해오던 관성을 깰 수 있도록 다른 관점을 제시해주셔서 고맙다는 마음을 전해주셨고, 저 역시 어쩌면 제 고집일 수도 있었지만 웹 표준과 프런트엔드를 고려해 흔쾌히 수고를 감수해주신 K님께 감사함을 전했습니다.
비즈니스의 장기적 유지에는 기술적으로 설명할 수 없는 라포와 팀워크도 동반됩니다. 함께 잘 챙겨야 해요.
표준은 최대한 지키자
기술에서의 표준은 환경과 나를 위한 규정이자 약속입니다. 단순히 라면 레시피를 다르게 해먹는 간단한 일이 아닙니다. 세계 표준이 C타입인데, 나는 5Pin을 들고 여행을 떠난다고 생각하면 얼마나 곤란할까요.
비즈니스적인 배경이나 사내외의 구조적 이유로 표준을 못 지킬 수도 있겠죠. 그럴 때를 위한 융통성도 당연히 있어야 합니다. 하지만 그럴 때에도 표준을 기준으로 삼고, 그로부터 어떻게 확장하거나 수정했는지를 명확히 해야 협업과 유지보수가 수월해질 것입니다.
저는 무턱대고 표준을 지키지 않으면 그때부터 히스토리가 생긴다고 생각합니다. 현재의 소통에도, 미래 세대의 유지보수에도 기술적 이해, 소통 비용이 뒤따를 것입니다. 오늘의 학습과 회고로 웹 표준은 더더욱 지켜야겠다고 생각했습니다.
긴 글 읽어주셔서 감사합니다. 😁😁
