API 응답(Response)에 관하여

1. API response를 처음 보았을 때

웹을 처음 시작하며 프론트 그리고 백엔드로 요청을 서로 주고받을 때는

그냥 json 형태로 필요한 것만 보내면 되겠지라고 생각하던 시절이 있었다

하지만 json을 보낼 때 단순히 당장 필요한 API 데이터만 보내는 것이 아니라

다른 인증, 성공 실패, 실패에 대한 처리 등이 생각 이상으로 중요 함을 알게 되었다.

그리고 그것을 어느 정도 규격화해 자동화 해야 하는 것 까지도

 

2. API 응답(Response)란?

API 응답은 클라이언트의 요청에 대해 서버가 작업 결과를 담아 돌려주는 데이터 꾸러미입니다

 

이 꾸리미에는 두 가지의 중요한 정보가 들어있습니다

 

1. HTTP 상태 코드 : 이 요청이 성공했는지 실패했는지 알려주는 부분

2. 데이터 본문 : 우리가 실제로 화면에 보여줘야 할 진짜 데이터가 있는 부분

 

3. API 응답의 본질

여기서의 개념을 잡았을 때 이해가 안 되는 부분이 있었습니다.

굳이 성공 실패에 대한 상태 코드를 보내지 않고

어디로 이동할지 모두 서버단에서 조절을 해주는 게 훨씬 편하지 않을까?라는 생각이 강하게 들었습니다.

하지만 이 생각이 이번에 모바일 관련 프로젝트를 하면서 생각이 바뀌게 되었습니다.

 

일단 첫 번째로 웹을 사용하는 경우에도 유연성이 떨어지기 때문에 상태 값을 넣는 것이 유연성 그리고 독립성 측면에서 유리합니다

 

로그인 페이지 주소가 /auth/login 에서 /signin으로 바뀌었다고 가정하면

서버가 담당할 경우에는 서버 개발자가 수정하고 다시 재 배포를 해야 한다고 하면

프트 담당이라면 프론트 앤드 코드만 수정하면 됩니다

 

UI/UX는 사용자의 피드백에 따라서 빈번하게 바뀌지만

데이터의 논리 즉 서버의 영역은 잘 바뀌지 않기 때문에 화면의 변화를 서버로부터 독립시키는 것이 더 효율적인 프로젝트 진행이 될 수 있다고 생각합니다.

 

이는 곧 결합도를 낮출 수 있게 되어 서버에서 코드 수정 시 발생하는 이상 상황을 줄일 수 있습니다.

 

마지막 이유는 기기에 따라서 대답이 달라야 하기 때문입니다.

처음에는 웹만 생각했지만 모바일까지 같이 생각했을 때는 선택이 아니라 필수임을 알 수 있었습니다

 

웹 사이트 : 에러 발생 시 특정 주소로 이동

아이폰 : 주소 개념이 없어서 따로 화면 객체를 띄워줘야 함

갤럭시 : intent 이용해 새로운 화면 실행

워치 : 메시지 띄우기

등 기기별로 화면을 전환하고 처리하는 방식이 다르기 때문에 error 코드를 보내서 기기에 따라서 각각 대응이 가능하도록 해야 한다.

 

그래서 API에 따른 서버 클라이언트 역할을 정리해보았습니다.

 

 

• 서버의 역할 (상태 전달): 현재 상황이 어떤지(200: 성공, 401: 인증 실패, 404: 없음 등) 명확한 "상태"만 전달
• 클라이언트의 역할 (행동 결정): 401이면 로그인 화면으로, 404면 에러 페이지로 사용자를 안내

 

 

4. 우리 프로젝트의 응답 설계

 

우리 프로젝트에서는 모든 응답을 status, message, data 3개 필드로 표준화하여 클라이언트와의 통신 효율을 높였습니다.

 

성공 케이스 (예: 소비 리포트 조회)

 

성공 시에는 명확한 안내 문구와 함께 필요한 데이터를 담아 보냅니다. AiTransactionController.java에서 처리되는 응답 예시는 다음과 같습니다.

JSON

 

{
  "status": "SUCCESS",
  "message": "소비 리포트 조회가 완료되었습니다.",
  "data": {
    "yearMonth": "2026-03",
    "totalSpent": 1943800,
    "spendingPersona": "쇼핑족",
    "aiOverallFeedback": "이번 달은 계획 대비 지출이 많은 편입니다."
  }
}

실패 케이스 (전역 예외 처리)

인증 실패나 잘못된 요청 시, GlobalExceptionHandler.java를 통해 일관된 에러 포맷을 제공합니다. 클라이언트는 이 FAIL 신호와 message를 보고 사용자에게 적절한 안내를 띄웁니다.

JSON

 

{
  "status": "FAIL",
  "message": "인증이 필요합니다.",
  "data": null
}

 

5. 실패를 대비한 "Fallback" 설계

이번엔 원래 기술의 의도는 아니지만 시연 시 안될 경우를 방지하여 fallback 설계를 이용했습니다.

서버에서 오류가 뜨더라도 fallback 로직을 이용해 저장된 값을 보여주는 형식입니다.

좀 더 다르게 이용한다면 사용자가 서비스를 끊김 없이 이용할 수 있도록 하는 좋은 서비스를 만들 수 있다고 생각합니다.

 

6. 마치며

API 응답에는 단순히 데이터를 보내기만 하면 되고 error는 애초에 안 나면 되지라는 편리한 생각을 했었는데요

error는 단순히 코드를 잘 짠다고 생기는 것이 아니라

 

다양한 상황

다양한 문제들이 생길 수 있기 때문에

반드시 필요하며 다양한 기기에 대응을 해야 한다는 점을 알 수 있었습니다.