API 응답 포맷 만들기

1. API 응답 클래스 생성

회사에서 제휴, 오픈마켓 API 서버를 구축할 때 사용했던 API 응답 포맷을 공유하고자 한다.
이 포맷은 개인 프로젝트인 ASAP 에서도 사용했다.

import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
public class ApiResult<T> {

  private int code;
  private String message;
  private T data;

  public ApiResult(T data) {
    this.message = "OK";
    this.data = data;
  }

  public ApiResult(ResponseCode code) {
    this.code = code.getCode();
    this.message = code.getMessage();
  }
}

ApiResult 라는 제네릭 클래스를 만들었다.
int 타입인 code는 API 응답 코드를 뜻한다. HTTP 응답 코드와는 다르니 혼동하지 않도록 한다.
String 타입인 message는 응답 메시지를 뜻한다.
제네릭 타입인 data는 응답 객체를 담는다.

2. 정상 처리 후 응답 객체로 응답할 경우

정상 처리 후 응답 객체로 응답할 경우에는, ApiResult(T data) 를 사용한다. code는 0, message는 “OK”, data에는 응답할 객체를 전달했다.

MissionDto missionDto = missionService.selectMissionInProgress(user);
return new ApiResult<>(missionDto);

{
  "code": 0,
  "message": "OK",
  "data": {
    "missionType": 1,
    "detail": [
      {
        "date": "20221126",
        "afternoon": 0,
        "night": 0
      }
    ]
  }
}

3. 정상/비정상 처리 후 상태값만 응답할 경우

정상/비정상 처리 후 상태값만 응답할 경우에는 ResponseCode 라는 enum 클래스를 사용하여 응답값을 정의했다.
이름과 code는 공통, 서비스별로 구분지어서 만들었다.

import lombok.Getter;

@Getter
public enum ResponseCode {

    // 공통
    COMM_S000(0, "OK"),
    COMM_E000(1000, "Internal Server Error"),
    COMM_E001(1001, "처리 중 에러가 발생하였습니다."),
    COMM_E002(1002, "파라미터가 잘못되었습니다."),

    // 닉네임
    NICK_E000(2000, "2자 이상 10자 이하로 입력해주세요."),
    NICK_E001(2001, "한글,영문,숫자로 입력해주세요."),
    NICK_E002(2002, "중복된 닉네임입니다."),

    // 미션
    MISS_E000(3000, "진행중인 미션이 있습니다."),
    MISS_E001(3001, "참여 가능한 시간이 아닙니다."),
    MISS_E002(3002, "변경한 이력이 없습니다.");

    private final int code;
    private final String message;

    ResponseCode(int code, String message) {
        this.code = code;
        this.message = message;
    }
}

이 경우에는 ApiResult(ResponseCode code) 를 사용하여 아래와 같이 리턴했다.

return new ApiResult<>(ResponseCode.MISS_E000);

{
  "code": 3000,
  "message": "진행중인 미션이 있습니다.",
  "data": null
}

위와 같이 응답 포맷을 미리 정의해놓으면, 코드도 간결해지고
응답 유형을 한 곳에 모아놓고 관리하기가 용이해지는 장점이 있다.