RESTful API 설계가 답일까? 기능 중심 URL로 바꾸기까지의 기록

서론

Prolog

처음에는 나도 그랬다.
“RESTful이 정석이라는데 그렇게 해야지 뭐...” 하고 아무 의심 없이 /api/v1/sellers/download 같은 주소를 쓰기 시작했다.
하지만 프로젝트가 점점 커지고,
CSV, NLP 모델, 학습데이터, 백오피스 다운로드까지 붙다 보니
URL이 점점 복잡하고 헷갈리기 시작했다.

---

본론

RESTful이란?

RESTful이란, “자원(Resource) 중심으로 URL을 구성하는 방식”이다.

예를 들어, users라는 자원을 다룰 때는 이렇게 URL을 짠다:

• GET /users – 유저 목록 조회
• POST /users – 유저 생성
• GET /users/1 – 특정 유저 정보 조회
• PUT /users/1 – 특정 유저 정보 수정
• DELETE /users/1 – 특정 유저 삭제

이처럼 자원 + 동사(method) 조합으로 구성되며, 깔끔하고 표준화된 구조 덕분에 협업에도 유리하다.
그래서 많은 개발자들이 RESTful을 "API 설계의 정석"으로 여긴다.
하지만… 모든 상황에 잘 맞는 건 아니다.

---

URL이 점점 복잡해지기 시작했다

예를 들어 이런 API가 생겼다:

• /api/v1/sellers/export
• /api/v1/sellers/download
• /api/v1/seller-dataset/csv
• /api/v1/brands/export-training-dataset

이게 뭐야… 뭘 export하고, 뭘 csv로 주는 건지 주소만 봐선 감이 안 온다.
파일명도 안 보이고, 구조도 들쭉날쭉하고.

---

그래서 결국 바꿨다

기능 중심 주소로.

• /download/seller-db-csv
• /download/brand-product-dataset
• /export/product-category-training-dataset

딱 보면 뭔지 보이고, 백오피스에서 호출할 때도 편하고,
기능 단위로 나뉘니까 API 관리도 쉬워졌다.

---

내가 내린 결론

• RESTful은 멋지지만 항상 정답은 아니다.
• 툴용 API, CSV 다운로드, 백오피스 전용 API는
  기능 중심 URL이 훨씬 직관적이다.
• 결국 프로젝트 목적과 맥락에 맞게 설계하는 게 진짜 실력이다.

---

상황별 정리

상황	URL 스타일
프론트엔드에서 쓰는 JSON API	/api/v1/resources (RESTful)
크롤러/툴에서 쓰는 CSV API	/download/파일명 (기능 중심)

RESTful은 선택이다.
꼭 고집하지 않아도 된다.
우리에게 중요한 건 실용성과 가독성일 때도 많다.