..

Modern Beautiful API Response Design: Prologue

TOC

  1. Overview
  2. 목표
  3. 연재 계획
  4. 약속 (Our Principle)
  5. Next Step

Overview

API 응답 시스템은 보통 프로젝트 후반에 뒤늦게 손보게 된다. 초반에는 기능 구현이 우선이라 예외 메시지, HTTP 상태 코드, 에러 JSON 포맷이 제각각으로 흩어지기 쉽다.

하지만 시스템이 커질수록 이 파편화는 곧 협업 비용이 된다. 프론트엔드는 매번 다른 에러 형태에 맞춰 분기해야 하고, 백엔드는 로그에서 의도된 비즈니스 실패와 실제 장애를 구분하느라 시간을 낭비한다.

견고하고 예측 가능한 API를 만들려면 세 가지를 함께 설계해야 한다.

  1. 예외를 어떤 기준으로 분류할 것인가
  2. 그 예외를 어떤 공통 응답 포맷으로 번역할 것인가
  3. 그 번역 책임을 아키텍처 어디에 둘 것인가

이 시리즈는 바로 이 세 질문에 답하기 위한 글이다. 첫 글에서는 전체 그림과 연재 순서를 정리하고, 이어지는 글들에서 예외 계약, 응답 포맷, 예외 핸들러의 위치를 순서대로 다룬다.

목표

이 시리즈가 해결하려는 핵심 목표는 아래와 같다.

  • 예외 계약 정리: 예외를 계층별로 분류하고, 상태 범주와 식별 코드를 분리한다.
  • 응답 포맷 통일: 내부 예외를 일관된 외부 API 응답으로 번역한다.
  • 아키텍처 정합성 확보: 예외 번역 책임을 헥사고날 아키텍처에 맞는 위치에 둔다.

연재 계획

  1. [프롤로그] 왜 API 응답 설계를 별도로 다뤄야 하는가
    현재 글 보기
  2. [1편] 서버 내부에서 실패를 어떻게 모델링할 것인가: Internal Exception Model
    modern-beautiful-api-response-design-internal-exception-model.html
  3. [2편] 클라이언트에게 어떤 에러 계약을 보여줄 것인가: External Error Contract
    2026-03-17-modern-beautiful-api-response-design-external-error-contract.html
  4. [3편] 내부 모델과 외부 계약을 어디서 연결할 것인가: Exception Translation Layer
    2026-03-18-modern-beautiful-api-response-design-exception-translation-layer.html

약속 (Our Principle)

  • 분리: 예외 분류, 응답 포맷, 번역 책임을 한 글에 모두 밀어 넣지 않는다.
  • 명확성: 클라이언트와 서버가 모두 이해할 수 있는 안정적인 계약을 지향한다.
  • 정합성: 단순한 코드 스타일이 아니라 아키텍처 책임 분리까지 함께 검토한다.

Next Step

다음 포스트에서는 Modern Beautiful API Response Design: Internal Exception Model 을 다룬다. 먼저 서버 내부에서 실패를 어떻게 모델링할지부터 정리한다.