API 응답 모델 고안

[Dr-KoKo]

API를 구현하면서 공통된 응답을 위해 모델을 만들 필요가 생겼습니다. 따라서 하단의 클래스를 만들었습니다.

public class ApiResponse<T> {
	private String code;
	private String message;
	private T data;

	private ApiResponse(String code, String message) {
		this.code = code;
		this.message = message;
	}

	private ApiResponse(String code, String message, T data) {
		this.code = code;
		this.message = message;
		this.data = data;
	}

	public static <T> ApiResponse<T> ok(T data) {
		return new ApiResponse<>("OK", "success", data);
	}

	public static <T> ApiResponse<T> error(ErrorCode errorCode) {
		return new ApiResponse<>(errorCode.getCode(), errorCode.getMessage());
	}

	public String getCode() {
		return code;
	}

	public String getMessage() {
		return message;
	}

	public T getData() {
		return data;
	}
}

public enum ErrorCode {
	AUTH_DUPLICATE_EMAIL("a1", "이미 가입된 이메일 입니다."),
	SIGNUP_INVALID_REQUEST("s1", "잘못된 요청입니다.");

	private final String code;
	private final String message;

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

	public String getCode() {
		return code;
	}

	public String getMessage() {
		return message;
	}
}

이 구조는 컨트롤러에서 body에 ApiResponse를 담아서 응답하는 구조입니다. 예외 발생시 ApiResponse.error(ErrorCode)를 호출하게 됩니다.

모든 API에 공통되는 모델이므로 팀 내에서 합의가 필요할 것 같습니다. 의견있으시면 자유롭게 공유해주세요.

[Hyeon-Uk]

저는 아래와 같은 포멧을 주로 사용합니다!

{
  success 혹은 status : 해당 값,
  response : data, //error면 null
  error : { //error가 없으면 null
    code : errorCode,
    message : errorMessage
}

이렇게 사용하게 된다면 성공하게 된다면 클라이언트에서 response만 바라보면 되고, 실패하게 된다면 error만 바라보면 되기 때문에 간편했어요 :)

저의 ApiUtil은 아래와 같아요!

public class APIUtils {

    public static <T> ResponseEntity<ApiResult<T>> result(boolean success, T response, HttpStatus status) {
        return new ResponseEntity<>(new ApiResult<>(success, response, null), status);
    }

    public static ResponseEntity<ApiResult<ApiError>> error(CustomException exception) {
        return new ResponseEntity<>(
                new ApiResult<>(false, null, new ApiError(exception))
                , exception.getErrorCode().getStatus());
    }

    @Getter
    @Setter
    public static class ApiResult<T> {
        private boolean success;
        private T response;
        private ApiError error;

        public ApiResult(boolean success, T response, ApiError error) {
            this.success = success;
            this.response = response;
            this.error = error;
        }

        public ApiResult() {
        }
    }

    @Getter
    @Setter
    public static class ApiError {
        private String code;
        private String message;

        public ApiError(String code, String message) {
            this.code = code;
            this.message = message;
        }

        public ApiError() {
        }

        public ApiError(ErrorCode code) {
            this(code.getCode(), code.getMessage());
        }

        public ApiError(CustomException exception) {
            this(exception.getErrorCode());
        }
    }
}

[june-777]

Controller

@GetMapping("/recruitments/{recruitmentId}")
public RecruitmentDetailsResponse readRecruitmentDetails(@PathVariable("recruitmentId") final Long recruitmentId) {
  return recruitmentDetailsFindService.findRecruitmentDetails(recruitmentId);
}

@GetMapping("/recruitments/popular")
public PopularRecruitmentsResponse readPopularRecruitments(@ModelAttribute PopularRecruitmentCond request) {
  return popularRecruitmentsFindService.findPopularRecruitments(request);
}

@PostMapping("/studies/{studyId}/recruitments")
public RecruitmentDetailsResponse write(@PathVariable("studyId") final Long studyId, @RequestBody final WriteRecruitmentRequest request,											@Parameter(hidden = true) @AuthUser final User user) {
  return recruitmentService.write(user, request, studyId);
}

ResponseBodyAdvice

성공 응답에 대해 공통 API 응답 명세에 맞는 ResponseBody를 매핑해줍니다.

@Component
@RestControllerAdvice
public final class CommonResponseAdvice implements ResponseBodyAdvice<Object> {

@Override
public boolean supports(final MethodParameter returnType, final Class<? extends HttpMessageConverter<?>> converterType) {
  return converterType.isAssignableFrom(MappingJackson2HttpMessageConverter.class);
}

@SneakyThrows
@Override
public Object beforeBodyWrite(Object body, final MethodParameter returnType, final MediaType selectedContentType, final Class<? extends HttpMessageConverter<?>> selectedConverterType, final ServerHttpRequest request, final ServerHttpResponse response) 
{
  final DataFieldName annotation = returnType.getMethodAnnotation(DataFieldName.class);
  body = (annotation != null) ? CommonResponse.success(annotation.value(), body) : CommonResponse.success(body);
  return body;
}

ExceptionHandler

실패 응답에 대해 공통 API 응답 명세에 맞는 ResponseEntity를 매핑해줍니다.

@Component
@RestControllerAdvice
public final class GlobalExceptionHandler {

@ExceptionHandler(value = Exception.class)
public ResponseEntity<CommonResponse> handleException(Exception e) {
  return toResponseEntity(e, e.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
}

[Dr-KoKo]

24-08-12 회의 내용입니다.

API 응답 모델

1. 컨트롤러 반환 타입

• 결제 중복 요청(따닥)을 방지하기 위해 만료되어 있는 경우 등 던지는 코드가 따로 있는 것으로 알고 있음
• 409 Conflict 등과 같은 HttpStatusCode를 컨트롤러에서 ResponseEntity를 던지는게 더 명확하겠다.
• 성공에 대한 상태 코드를 세분화하는게 클라이언트 측이 조금 더 명시적일 것

2. POST

• restController → 201 OK + Location Header
• Controller → PRG

3. CSR vs SSR 기준이 모호함

• 현재는 모두다 restController로 구현되어 있음. 이렇게 되면 결국 CSR로 될 것 같다는 고민
  → 일단 rest하게 구현해놓고, 뷰는 나중에 고민하자.

4. ProblemDetail (RFC 9457)

• Spring에서 제공하는 ProblemDetail 활용해서 예외처리
• 성공/실패 케이스에 대해 명확하게 분리하기 어렵다고 판단.
  • 세부적인 상황에 대해 고민이 생기면 언젠간 컨벤션이 깨지기 쉬움
  • 따라서 간단하고 관리하기 용이한 구조로 가져가자.

결론

1. 컨트롤러에서는 ResponseEntity를 반환한다.

2. 예외가 발생하면 ProblemDetail을 활용한다.

3. 성공: 2xx + ApiResponse / 실패: 4xx + ProblemDetail(+errorCode)로 세부 명시

ex) 예시

• 성공 케이스:

  {
  	"status": "성공 상태 코드(2xx)",
  	"data" : {
  		"id" : "id values",
  		"pw" : "pw values"
  	}
  }

• 실패 케이스:
  ProblemDetail 를 활용하고, 해당 명세를 따른다. + errorCode 필드 하나 추가

  {
  	"type" : "type을 명시",
  	"title" : "title을 명시",
  	"status" : "error status code를 명시",
  	"instance" : "instance? 를 명시",
  	"errorCode" : "custom error code를 명시",
  	"message" : "error에 대한 구체적인 메세지 명시"
  }