좋은 API Response 만들기 리뷰

좋은 API Response 만들기

그래야하지 않을까? 싶었지만 하지 않았던 습관들에 대해 지적해주는 글이 아닌가 싶다.

최소 스펙 유지하기

가능한 API 크기를 최소화 한다.
즉, DTO를 중복적으로 사용하지 않는게 중요한 듯 하다.
회사에서 레거시한 프로젝트들을 관리하다 보면 하나의 통합적인 DTO(예를들면 상점 도메인에 사용하는 모든 데이터(!!)를 적어둔 ShopDTO)를 만들어 놓고
중복적으로 사용하며 Response에는 null 값이 숭숭 뚫려있는 프로젝트들이 있었다.

이게 참 백엔드 개발자로써는 중복된 코드를 지양하고(!) 객체지향인것(!) 싶지만
단순히 레이어 간의 파라미터의 역할을 하는 객체를 객체지향 코드로 격상시켜 버린 것이 아닐까 싶다.(그리고 이런 response api를 받으면 프론트 개발자 분들이 쌍욕한다ㅋㅋ)

나는 메서드 단위의 ResponseDTO를 만들어 사용하고 있다.
아무리 중복되는 인자가 있어도 DTO를 2개 이상의 메서드에 반환하는 일은 최소한으로 해둔다.(뭐 정말 똑같은 경우는 어쩔 수 없지만)
DTO 내부의 innerClass 도 지양하고 있다. 하나의 클래스가 너무 커지게 되고 DTO를 부를때도 한줄에 너무 길게 적히다 보니 가독성이 안좋아지는 코드를 많이 보게 되었다.

        MemberDTO.MemberXXXResponse response = MemberRepository.findBy....

camelCase 사용하기

문제없다.

표준 포맷 사용하기

사용자에 노출되는 데이터에는 날짜데이터를 포맷팅 하거나 Date 클래스로 전달하였지만
사용자에게 노출이 안되는 데이터들(jwt 토큰의 만료시간 등등)에는 UNIX 타임스탬프를 사용한 적이 있었던 것 같다.
이 점도 고치도록 하자.

Boolean 타입에는 null 이 있으면 안된다.

정말 부끄럽지만 Boolean의 null 값을 하나의 상태값으로 사용한 적이 있다.
참과 거짓의 열거형인데 이것을 true or false or null 으로 사용하였다.
블로그에서도 각각 의미가 있다면 YES, NO, UNKNOWN 으로 표현하는 것을 권장한다.

제한된 문자열 값은 열거형 (Enum) 으로 표현한다.

간혹 시간에 쫓겨 열거형을 사용해야함에도 불구하고 String 으로 DB를 설계하는 경우가 있는데 이런 부분도 신경쓰면서 사용하자.

열거형 (Enum)은 문자열로 표현되어야 한다.

Entity를 설계할 때 @Enumerated(EnumType.STRING) 어노테이션을 사용하여 관리하고 있다.

복수형 빈 값은 빈 배열로

단일 객체에 Null Object Pattern을 대응 하는 것은 기존 시스템의 상황에 따라 기본값을 구현하기 어렵거나 Null 자체가 유의미한 경우가 많아 상황에 따라 선택한다.

복수형 객체를 반환할때 null 일 경우 빈 배열로 전달하도록 하자. 생각도 못해봤다.

일관성 유지하기

결국 네이밍의 중요성인데, 아직까지 네이밍을 구분하기 쉽게 잘(?) 짓는다고 할 수 없어서 항상 생각하면서 네이밍을 짓도록 하자.

필드명 축약 금지, 타입에 맞는 필드명

• 필드명을 축약하는 것이 버릇이 된다면 나중가면 본인만 알고 전혀 의미를 알 수 없기 때문에 고치도록 하자
• Boolean 타입이라면 is, has 등을 prefix로
• 일시 타입이라면 At 을 suffix로
• 복수형은 복수형으로

우리 회사의 경우 At을 사용하지 않고 date를 사용하고 있다.(At은 올드해보인다는 말 때문에..)
복수형의 경우는 복수형도 있지만 xxxList 등의 방식으로 반환하고 있다.