API & Response Body 형태 구성

스타트업 백엔드 인턴으로 근무하여 배운 내용을 까먹지 않기 위해 정리하는 글입니다.

 

# API 형태 구성

• API 반환 값은 Json Object (Key, Value)로 구성하는 것이 좋다. 그래야 프론트에서도 (Key, Value)로 접근하기 편리하고, 확장성도 좋다.
• 응답 코드도 함께 반환해주는 것이 좋다. 응답 메시지는 변경될 가능성이 크기 때문에 프론트에서 처리할 때 응답 코드로 처리하는 것이 훨씬 편하다. 

 

느낀점

파피메일 프로젝트를 할 때는 응답 메시지만 다르게 반환해서 프론트에서 구별해주셨는데 미안한 마음이 들었다. 다음 프로젝트 때는 응답 코드도 필수로 반환하도록 개선해야겠다.

 

# Response Body 형태

응답 코드, 응답 메시지를 포함한 통일된 응답 형태로 반환하기 위해 ResponseService 클래스를 만들어 기본 틀을 구성해둔다.

@Service
public class ResponseService {

	...

    /**
     * enum으로 api 요청 결과에 대한 code, message를 정의합니다.
     */
    @Getter
    @AllArgsConstructor
    public enum CommonResponse {
        SUCCESS(0, "성공하였습니다."),
        FAIL(-1, "실패하였습니다."),
        SMS_SEND(1000, "입력하신 전화번호로 인증번호가 발송되었습니다."),
        SMS_PHONE_AUTH_SUCCESS(1010, "인증이 완료되었습니다.");

        int code;
        String msg;
    }

    /**
     * 단일건 결과를 처리하는 메소드
     */
    public <T> SingleResult<T> getSingleResult(T data) {
        SingleResult<T> result = new SingleResult<>();
        result.setData(data);
        setSuccessResult(result);
        return result;
    }

    /**
     * 다중건 결과를 처리하는 메소드
     * @param list
     * @param <T>
     * @return
     */
    public <T> ListResult<T> getListResult(List<T> list) {
        ListResult<T> result = new ListResult<>();
        result.setList(list);
        setSuccessResult(result);
        return result;
    }

    /**
     * 성공 결과만 처리하는 메소드
     * @return
     */
    public CommonResult getSuccessResult() {
        CommonResult result = new CommonResult();
        setSuccessResult(result);
        return result;
    }

    /**
     * 실패 결과만 처리하는 메소드
     * @return
     */
    public CommonResult getFailResult(int code, String msg) {
        CommonResult result = new CommonResult();
        result.setSuccess(false);
        result.setCode(code);
        result.setMsg(msg);
        return result;
    }

    /**
     * 결과 모델에 api 요청 성공 데이터를 세팅해주는 메소드
     * @param result
     */
    private void setSuccessResult(CommonResult result) {
        result.setSuccess(true);
        result.setCode(CommonResponse.SUCCESS.getCode());
        result.setMsg(CommonResponse.SUCCESS.getMsg());
    }

    private void setFailResult(CommonResult result) {
        result.setSuccess(false);
        result.setCode(CommonResponse.FAIL.getCode());
        result.setMsg(CommonResponse.FAIL.getMsg());
    }
	
    ...
}

 

🎈참고

REST API 구조 설계하기