API 응답 형식 표준화: 즐겨찾기 서비스 개선

들어가며

API 응답 형식의 표준화는 백엔드 개발에서 매우 중요한 부분입니다. 일관된 응답 형식은 API를 사용하는 클라이언트 개발자의 개발 경험을 크게 향상시키고, 프로젝트의 유지보수성을 높여줍니다. 하지만 개발 초기 단계에서는 이러한 표준화의 중요성을 간과하기 쉽습니다. 빠른 기능 구현에 집중하다 보면, 각 API 엔드포인트마다 서로 다른 응답 형식을 가지게 되고, 이는 결국 기술 부채로 남게 됩니다.

저희 팀도 작품 즐겨찾기 서비스를 개발하면서 이러한 문제를 경험했습니다. 프론트엔드 개발자가 API 연동 시 매번 다른 방식으로 응답을 처리해야 했고, 에러 처리도 일관성이 없었습니다. 이에 따라 API 응답 형식을 표준화하는 작업을 진행하게 되었고, 그 과정에서 많은 것을 배울 수 있었습니다.

문제 인식

처음 API를 설계할 때는 각 기능의 특성만 고려했습니다. 즐겨찾기 목록을 조회하는 API는 단순히 목록만 반환하면 된다고 생각했고, 즐겨찾기를 추가하는 API는 추가된 결과를 엔티티 그대로 반환했습니다. 당시에는 이것이 가장 직관적인 방법이라고 생각했습니다.

하지만 서비스가 커지고 API가 늘어나면서 문제점들이 하나둘 드러나기 시작했습니다. 프론트엔드 개발자는 각 API마다 다른 방식으로 응답을 처리해야 했고, 에러가 발생했을 때 어떤 API는 상세한 에러 메시지를 제공하는 반면 어떤 API는 단순히 실패 여부만 알려주었습니다. 또한 Artist 엔티티를 직접 반환하는 경우도 있어서, 불필요한 정보가 노출되는 보안 이슈도 있었습니다.

개선 과정에서의 고민

API 응답 형식을 표준화하면서 가장 많이 고민했던 부분은 '얼마나 상세한 정보를 포함할 것인가'였습니다. HTTP 상태 코드를 응답 body에 포함할 것인지, 성공과 실패 응답의 구조를 다르게 가져갈 것인지에 대해 팀 내에서 많은 논의가 있었습니다.

논의 후에 저희 팀은 다음과 같은 원칙을 세웠습니다:

1. HTTP 상태 코드는 헤더에만 포함하고 body에서는 제외
2. 성공/실패 응답 구조는 동일하게 가져가되, code 필드로 구분
3. 비즈니스 로직 결과는 data 필드에 담고, 부가 설명은 message 필드에 포함

개선된 코드

이러한 원칙을 바탕으로 코드를 전면적으로 개선했습니다. 특히 즐겨찾기 폴더 간 작품 이동 API의 경우, 작업 결과와 함께 현재 전체 즐겨찾기 상태를 반환하도록 변경했습니다. 이는 프론트엔드에서 추가적인 API 호출 없이도 UI를 즉시 업데이트할 수 있게 해주었습니다.

예를 들어, 즐겨찾기에 작품을 추가하는 API는 다음과 같이 변경되었습니다:

{
    "code": "SUCCESS",
    "message": "작품이 즐겨찾기에 추가되었습니다.",
    "data": {
        "favoriteFiles": [
            {
                "fileName": "기본",
                "artworkIds": ["667152928508511115152bd8"],
                "artworkCount": 1
            }
        ],
        "totalFavoriteCount": 1
    }
}

특히 에러 처리의 경우, 모든 API가 동일한 형식으로 에러 정보를 반환하도록 표준화했습니다:

{
    "code": "FAVORITE_FILE_NOT_FOUND",
    "message": "즐겨찾기 파일을 찾을 수 없습니다: my_favorites",
    "data": null
}

개선 효과

표준화된 응답 형식은 즉각적인 효과를 가져왔습니다. 프론트엔드 팀에서는 API 응답 처리를 위한 공통 모듈을 만들 수 있게 되었고, 이는 개발 생산성을 크게 향상시켰습니다. 에러 처리도 더욱 견고해져서 사용자에게 더 나은 피드백을 제공할 수 있게 되었습니다.

백엔드 측면에서도 코드 품질이 크게 개선되었습니다. GlobalExceptionHandler를 통해 모든 예외가 일관되게 처리되었고, 새로운 API를 추가할 때도 기존 패턴을 따르기만 하면 되어 개발 속도가 빨라졌습니다.

마치며

이번 개선 작업을 통해 API 설계에서 표준화의 중요성을 다시 한 번 깨달았습니다. 단순히 기능이 작동하는 것을 넘어서, 어떻게 하면 더 나은 개발자 경험을 제공할 수 있을지 고민하는 것이 중요하다는 것을 배웠습니다.

앞으로는 새로운 기능을 개발할 때도 이러한 표준화된 패턴을 처음부터 적용할 계획입니다. 또한 현재의 응답 형식도 계속해서 발전시켜 나갈 예정입니다. 특히 현재 별도로 관리되고 있는 비즈니스 에러 코드들을 체계적으로 정리하고, 응답 메시지의 일관성을 더욱 높이는 작업을 진행하고자 합니다. 더불어 API 문서화를 자동화하여 프론트엔드와의 협업을 더욱 원활하게 만들어갈 계획입니다.

API는 프론트엔드와 백엔드를 이어주는 다리입니다. 이 다리가 얼마나 견고하고 사용하기 쉬운지가 전체 서비스의 품질을 좌우한다는 것을 이번 기회를 통해 다시 한 번 확인할 수 있었습니다.