작업하던 프로젝트에서 이번 글의 주제에 해당하는 정말 많은 API가 있었지만 대표적으로 게시글 조회를 위한 API로 글을 써보도록 써본다.
발단
메인으로 작업하고 있던 프로젝트가 한창이던 시기로, 평소와 같이 JSON 상하차를 하고 있었다.
개발자가 되기 위해 막 입문한 시기였고, 포켓몬으로 치면 발버둥밖에 못 하는 잉어킹수준 이었다.
REST API라는 말은 대충 알고 있었지만, 세부적인 내용은 몰랐다.
대충 path로 계층을 표현하고 행위에 대해서는 HTTP Method로 표현하고 대문자 대신 소문자 등등의 정도만 알고 따로 리서치를 해보지는 않았었다.
결국 REST API의 빙산의 일각도 모르던 나는 단순 게시글을 Pagination 형식으로 전체 조회하는 API를 3개, 혹은 그 이상 만들었었다(Response schema가 달라지는 것도 아니다).
즉, 클라이언트 측에서 요청하면 요청하는 대로 등신처럼 API를 새로 싸질렀다.
그리고 따로 사이드 프로젝트를 같이 하던 선배가 내가 한 기행들을 보고 링크를 던져줬다.
문제
문서 내의 새 API에 대한 리소스 URI를 만들 때 참조할 만한 Best Practices에서 해당 글의 주제에 아주 딱 맞는 부분이 눈에 들어왔다.
2.5. 쿼리 구성 요소를 사용하여 URI 수집 필터링
종종 특정 리소스 속성을 기반으로 정렬, 필터링 또는 제한되는 리소스 컬렉션이 필요한 요구 사항에 직면하게 됩니다.
이 요구 사항을 충족하려면 새 API를 생성하지 마세요. 대신 리소스 컬렉션 API에서 정렬, 필터링 및 페이지 매김 기능을 활성화하고 입력 매개 변수를 쿼리 매개 변수로 전달하세요. e.g./device-management/managed-devices /device-management/managed-devices?region=USA /device-management/managed-devices?region=USA&brand=XYZ /device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date
아 좀만 더 빨리 볼걸.. 하는 생각이 들었었다.
문제 해결
해당 문서에는 정말 많은 내용이 있지만 해당 글에서 다 적기엔 무리인 것 같다. 그래서 어떤 식으로 개선했는지 살펴보자.
밑의 URI는 기존의 게시글 조회와 관련한 URI 들이다.
/mentor-board
/mentor-board/hot-posts
/mentor-board/pulling-up지금 봐도 이게 뭔가 싶다..
일단 리소스도 단수형으로 표현되어 있고 hot-posts, pulling-up은 각각 멘토 게시판의 인기 게시글, 끌어 올려진 게시글(대충 게시글 상단으로 끌어 올리기 같은 느낌?)을 불러오는 URI 였다. 애초에 별개의 리소스 였다면 다른 리소스에 대한 접근인것 처럼 URI를 표현했으면 됐는데 그것도 아니었다.
그래서
/mentor-boards?loadOnlyHotPosts=true&loadOnlyPulledUpPosts=true
와 같은 형식으로 리소스를 복수형으로 표현했고 필터링을 Query paramter로 받도록 3개의 API를 하나의 API로 통합시켰다.
마무리
내 딴엔 RESTful 하게 API를 짰다고 생각했는데 그러지 못한 경우가 참 많은 것 같다. 물론 이 글의 문제 해결 방법 또한 마찬가지일 수도 있다.
개발하고 관련 지식을 공부하는 게 정말 재밌긴 하지만 한편으로 느끼는 점은 참 갈 길이 먼 것 같다...
출처:
