🌿 중급 백엔드
API 응답은 어떻게 구조화하나요?
쉽게 이해하기
택배 상자가 항상 같은 형식(보낸이, 받는이, 내용물)으로 정리되어 있으면 찾기 쉬운 것처럼, API 응답도 정해진 형식(success, data, error)으로 보내면 처리하기 편해요. 매번 다른 방식으로 오면 혼란스럽죠.
핵심 정리
API 응답을 일관된 구조로 만들면 프론트엔드 개발자가 데이터를 다루기 훨씬 쉬워져요.
자세히 알아보기
API 응답을 설계할 때 가장 중요한 건 일관성이에요. 성공이든 실패든 항상 같은 구조를 유지해야 해요. 많이 쓰이는 패턴은 이런 거예요: { "success": true, "data": {...}, "message": "성공" }
성공 응답에는 실제 데이터를 data 필드에 담아요. 리스트를 반환할 땐 페이징 정보도 함께 보내는 게 좋아요. { "success": true, "data": { "items": [...], "page": 1, "totalPages": 10 } } 이런 식으로요.
에러 응답도 구조화가 중요해요. { "success": false, "error": { "code": "INVALID_EMAIL", "message": "이메일 형식이 올바르지 않습니다" } } 같은 식이죠. 에러 코드를 명확히 정의하면 프론트엔드에서 각 상황에 맞는 처리를 할 수 있어요.
실무에서는 응답 형식을 팀 전체가 합의해서 문서화해요. JSend, JSON:API 같은 표준 규약을 따르기도 하죠. 중요한 건 일관성을 유지하는 거예요. 어떤 API를 호출하든 같은 방식으로 응답을 처리할 수 있어야 프론트엔드 코드가 간결해지고 버그도 줄어들어요. 특히 에러 처리 로직을 한 곳에서 관리할 수 있게 되면 유지보수가 훨씬 편해져요.