조회 API에 필터링과 검색이 들어온다면?

안녕하세요! 오늘은 방끗의 새로운 기능을 개발하면서 API 설계에 논의한 / 논의할 내용을 글로 정리해 보려고 합니다 👍

저희 방끗의 디자이너 분께서 열일해 주셨습니다

API를 설계해 보자

저희가 대대적인 새로운 기능 도입을 앞두고 추가 기능이 많아졌다는 소식은 앞선 게시물을 통해 전달해 드렸는데요

리스트 조회를 하며 유저의 경험 편리성을 향상시키기 위해 다양한 필터링과 검색 조건을 추가하게 되었습니다

필터링 조건들: 현재 위치 기준, 지하철 기준, 오늘 올라온 건물
검색 조건들: 건물명, 위치, 지하철

현재 기능에서는 위와 같은 필터링과 검색이 필요합니다
저는 API를 설계하면서 고민되는 지점이 있었어요

과연 어디까지를 API로 따로 분리해야 될까?

해당 API들은 모두 특정 조건에 따라 건물 리스트 조회를 응답값으로 주게 되고,
모두 응답 포맷은 동일한 API들입니다

파라미터, 혹은 본문을 이용해서 조건을 전달한다면 충분히 하나의 API로 구현이 가능할 것입니다

하지만 그것이 설계적으로도 괜찮을까요? 개발자들이 소통하기에 괜찮은 포맷일까요?

개념적으로 나누어 보자

위 조건들을 크게 세 가지로 나누어 볼 수 있을 것 같습니다

1. 오늘 올라온 건물 필터링
홈 화면에서 오늘 올라온 건물을 보여 주는 API입니다
유저의 직접적인 입력 없이, 요청마다 파라미터가 달라지지 않는 API예요

2. 현재 위치 기준 필터링
유저의 입력이 아닌 지도에서 위치를 옮길 때마다 특정 반경에 해당하는 건물을 응답값으로 돌려주는 API입니다
유저의 직접적인 입력 없이, 요청마다 파라미터가 달라질 수 있는 API예요

3. 건물명 기준 검색, 위치 기준 검색, 지하철 기준 검색

지하철 기준 필터링과 지하철 기준 검색은 동일한 역할을 하기 때문에 합쳐서 보겠습니다
또한 현재 단계에서는 무엇을 기준으로 검색했는지 서버에서 판단하는 것이 아닌, 유저가 선택해서 검색했다고 가정하겠습니다

유저가 직접 필터링을 하거나 검색을 할 때 해당하는 건물들을 응답값을 돌려주는 API입니다
유저의 직접적인 입력이 있고, 요청마다 파라미터가 달라질 수 있는 API예요

어떻게 설계해 볼까?

먼저 1번의 경우에는 소통의 직관성과 API의 재활용성을 생각해서 따로 API를 설계해도 된다고 생각합니다!

"오늘 올라온 건물"이라는 명확한 목적을 가진 API는, 이를 전담하는 엔드포인트를 분리함으로써 클라이언트와 서버 간의 소통이 더 명확해집니다
뿐만 아니라, 명확한 역할을 가진 API는 향후 로직 변경, 캐싱, 로깅 등 유지보수 측면에서도 관리가 수월할 거라고 생각했습니다!

그렇다면 2번과 3번은 어떻게 설계하는 게 좋을까요?

✅ 함께 설계 : 하나의 API + 파라미터 분기 처리

• 장점
  클라이언트 입장에서 통일된 방식으로 호출 가능 (/buildings 하나로 통합)
  공통 로직(페이징, 정렬 등)을 재사용하기 쉬움
  필터 기준이 점점 늘어날 때 구조적으로 유연

• 단점
  파라미터 조합이 복잡해질 수 있음 (e.g., type=keyword, subwayId, lat/lng, isToday=true 등)
  API 문서 가독성 저하 → 각 케이스별 설명이 필요
  필터별 로직이 복잡해지면 코드 유지보수가 어려워질 수 있음

✅ 따로 설계 : 기능별로 API를 나누는 방식 (엔드포인트 분리)

• 장점
  명확한 역할 분리 → 유지보수 및 API 문서화에 유리
  각 API에 맞는 최적화된 처리 가능 (e.g., 캐싱, 쿼리 튜닝)
  추후 각 기능을 독립적으로 개선하거나 제거하기 쉬움

• 단점
  클라이언트는 어떤 API를 호출해야 할지 로직을 더 알아야 함
  API 수가 늘어나면서 라우팅 구조가 복잡해질 수 있음

저는 2번(현재 위치 기준)과 3번(검색 기반)은 API를 분리하는 것이 좋다고 생각했어요!

먼저, 위에서 나뉘었다시피 유저의 명시적인 입력 유무와 API의 목적이 뚜렷하게 다릅니다
또한, 2번과 3번의 서버 내부 구현이 아주 다르기 때문에, 파라미터에 따라 완전히 다른 로직을 수행하게 됩니다
UI 구성도 일반적으로 다르며, UX 흐름상 분리된 기능처럼 인식되기 때문에 API를 동일하게 둔다면 개발자 인식상의 혼동이 발생할 수도 있습니다

마무리

저는 위와 같이 생각하고 선택을 하였습니다
제가 고려하지 못한 부분이 있는지, 또 다른 시야의 개발자 분들이 계시는지 궁금해요!☺️
글 읽어 주셔서 감사합니다 🙇‍♂️

---

논의 결과

방끗 팀 내에서 활발한 논의를 해 본 결과, 그리고 제 사고가 바뀌게 되어
2번과 3번을 합치게 될 것 같아요

사유는 다음과 같습니다!

• 2번과 3번의 서버 내부 구현이 아주 다르기 때문에
  해당 부분을 소통의 측면에서 표시할 필요는 없다고 생각이 바뀌었습니다
  백엔드의 구현을 API 상으로 드러낼 필요가 있을까요?
  API 상으로 드러나는 부분은 "위치 기준으로 근처 빌딩을 조회"라고 생각이 들어요!

저희가 논의할 때 통일된 사안은
필터링, 검색, 정렬을 모두 리스트 조회 API에서 파라미터로 관리하고,
자주 조회되고 따로 사용될 API는 분리하는 것이었어요

이때 위치 기준으로 반경 n 안의 범위의 빌딩을 조회하는 것은 어느 범주로 볼까? 라고 질문을 던져봤을 때 필터링의 범주로 보고 진행하는 것이 흐름상 자연스럽게 느껴졌고,
FE 개발자가 API 문서를 참고할 때 당연히 필터링 파라미터를 보게 되지 않을까? 라는 생각이 들었습니다

따라서 이렇게 문서를 정리해 보았습니다~