API를 설계하거나 프로젝트를 진행하면서 "공통 응답 포맷"이라는 개념을 들어본 적이 있을 겁니다. 그렇다면 왜 공통 응답 포맷이 필요할까요? 이를 이해하기 위해 일상 속의 사례를 떠올려보죠.
만약 배달 음식을 주문했는데, 한 번은 포장지가 빨간색이고 한 번은 파란색, 또 다른 날은 포장지가 아예 없는 경우를 상상해보세요. 음식의 품질은 같을지 몰라도, 포장의 일관성 없는 모습은 불편함을 줄 것입니다.
API도 마찬가지입니다. 응답 형태가 매번 달라지면 클라이언트 개발자는 이를 처리하기 위해 불필요한 작업을 반복하게 됩니다. 공통 응답 포맷은 이러한 혼란을 방지하고, API 사용자(주로 클라이언트 개발자)와의 원활한 소통을 가능하게 합니다.
1. 공통 응답 포맷이 없다면?
공통 응답 포맷이 없다면 어떤 일이 벌어질까요? 간단한 예를 들어봅시다.
상황 1: 상태를 알 수 없는 응답
클라이언트가 서버로부터 200 OK를 받았지만, 실제 데이터가 null이거나 응답 데이터가 이해할 수 없는 형태라면 어떨까요?
이 응답이 정말 성공인지, 아니면 단순히 데이터가 없어서 null인 것인지 애매합니다. 이런 모호함은 클라이언트 측에서 불필요한 디버깅 작업을 유발합니다.
상황 2: 응답 형태가 제각각
이 경우 클라이언트는 엔드포인트마다 다른 데이터 파싱 로직을 구현해야 하므로 생산성과 유지보수성이 떨어집니다.
2. 공통 응답 포맷이 있다면?
공통 응답 포맷이 도입되면 상황은 어떻게 바뀔까요? 모든 API 응답이 동일한 구조를 가진다면, 클라이언트 개발자는 일관된 방식으로 데이터를 처리할 수 있습니다.
ex) JSON 기반 공통 응답 포맷
{
"status": 200,
"message": "요청이 성공적으로 처리되었습니다.",
"data": {
"userId": 1,
"name": "John"
}
}
위와 같은 포맷에서는 status로 요청의 성공 여부를 알 수 있고, message를 통해 부가적인 정보를 전달하며, data 필드에 실제 데이터를 담습니다. 이 구조는 API의 가독성을 높이고, 클라이언트가 응답을 파싱하는 로직을 단순화합니다.
3. 공통 응답 객체 설계 방법
공통 응답 객체는 일반적으로 다음과 같은 필드들로 구성됩니다:
- status: HTTP 상태 코드 또는 성공 여부를 나타내는 값.
- message: 성공 또는 에러 메시지.
- data: 실제 데이터를 담는 필드. 없을 경우 빈 객체나 null로 처리.
코드 예시: Spring에서의 구현
public class ApiResponse<T> {
private int status;
private String message;
private T data;
public ApiResponse(int status, String message, T data) {
this.status = status;
this.message = message;
this.data = data;
}
public static <T> ApiResponse<T> success(T data) {
return new ApiResponse<>(200, "요청이 성공적으로 처리되었습니다.", data);
}
public static <T> ApiResponse<T> error(String message) {
return new ApiResponse<>(500, message, null);
}
// Getter, Setter 생략
}4. 공통 응답 포맷의 장,단점
공통 응답 포맷의 장점
- 일관성: 응답 형태가 통일되어 클라이언트 개발자의 작업량 감소.
- 가독성: 응답 데이터를 쉽게 파악 가능.
- 유지보수성: 에러 처리 및 디버깅이 간편해짐.
- 확장성:새로운 필드를 추가해도 기존 클라이언트에 영향을 주지 않음.
단점 및 주의할 점
- 오버헤드:단순한 API에서도 필요 이상의 구조가 추가될 가능성.
- 유연성 부족:고정된 응답 형태가 특정 상황에서 제약을 줄 수 있음.
- 잘못된 설계:공통 포맷을 만들었지만 실제로 활용되지 않는 필드가 많아지는 경우.
5. 개발자와 클라이언트의 다리
공통 응답 포맷과 객체는 개발자와 클라이언트 간의 소통을 매끄럽게 하고, 유지보수성을 크게 향상시킬 수 있는 중요한 도구입니다. 공통 응답 포맷은 단순히 현재의 문제를 해결하는 도구가 아니라, 더 나은 API 환경으로 나아가기 위한 방향을 제시합니다.
공통 응답 포맷은 더 나은 협업을 위한 첫걸음