API를 개발할 때 어떤 Response를 사용하시나요??
저는 처음에는 단순 jsonObject를, JSP를 사용할 때는 Model을, jackson 을 사용한 이후에는 Dto를, 그리고 한번 더 Response 형식을 맞춰야 할 필요를 배우고는 spring http의 ResponseEntity 를 사용했습니다.
그리고 현재, 서버가 늘어나고 에러 케이스를 상세히 분류하게 되며 단순 HTTP ResponseEntity에서 제공하는 코드가 아니라, 우리 서비스의 상태 코드와 리스폰스 형식을 만들어야 할 필요성을 느꼈습니다.
Response body 가 책임져야 하는 것은 API 를 사용하는 프로그램에 처리 결과를 간략하게 전달하는 것(code), 개발자를 위한 메시지를 주는 것(message), 처리 결과 값(result)을 넘겨 주는 것이 될 수 있습니다.
때문에 일반적으로 다음과 같은 형식을 취합니다.
{
"code": 200000,
"message": "ok",
"data": {
}
}- code : 프로그램 코드 에서 사용. 처리 결과 상태.
- message : 개발자가 문서를 보지 않아도 알 수 있는 message 값
- data : API 가 전달해야하는 Resource 내용 혹은 처리 결과
CODE
개인적으로 code는 4자리~6자리를 주로 사용합니다. 서버 넘버, 상태 등을 포함해 어느 서버에서 어떤 리스폰스(혹은 에러)가 넘어왔는지 알 수 있도록 설계하는 것이 좋습니다.
아래와 같이 성공은 00, 정의되지 않은 에러는 99 등의 넘버를 주고, 예상 가능한 에러들에 대해 넘버를 붙여준다면 단순 404나 204 등 HTTP 상태 코드만 넘겨줄 때 보다 명시적인 소통이 가능합니다.
또한 서버간 통신이 필요한 기능일 경우에도 어떤 서버에서 문제가 생겼는지 추적할 수 있습니다.
MESSAGE
개발자가 상태 코드 문서를 찾아보지 않아도 알 수 있도록 리스폰스에 대한 정보를 제공하는 메세지입니다.
2006 같은 상태 코드만 봐서는 개발문서를 확인하지 않는 이상 해석할 수 없고, 상태 코드 또한 변경될 여지가 있기 때문에 메세지를 보고 해석할 수 있도록 합니다.
DATA
return 된 값이 있을 경우의 데이터입니다. 일반적으로 생각하는 body 에 들어가야 할 리소스나 시스템에 필요한 정보를 담아줍니다.
spring HTTP ResponseEntity를 Data로 취급해, custom ResponseEntity로 한번 더 감싸는 형태를 취하는 경우도 있습니다.
Ref.
http://blog.storyg.co/rest-api-response-body-best-pratics
https://tecoble.techcourse.co.kr/post/2021-05-10-response-entity/
