개발기초 REST API 설계하면서 겪은 실수와 배운 점 (실무에서 얻은 기준)

MES 서비스 백엔드 개발을 맡으면서 API 설계를 처음부터 담당한 적이 있습니다. 문서로 배운 REST 원칙과 실제 실무에서 API를 설계하는 건 꽤 다르다는 걸 그 과정에서 깨달았습니다.

상황: 왜 다시 설계를 고민하게 됐나

초반에 급하게 만든 API들이 있었는데, 기능이 늘어나면서 [엔드포인트가 뒤죽박죽되거나 / 프론트엔드 개발자가 API 스펙을 계속 다시 물어보는] 상황이 반복됐습니다. 이 시점에 설계 기준을 다시 세워야겠다고 판단했습니다.

문제 1: 엔드포인트 이름 규칙이 제각각이었다

초반에 급하게 만들다 보니 [/getUser, /user_list, /Users] 처럼 같은 리소스인데 표기 방식이 다 달랐습니다. 새 기능을 추가할 때마다 "이번엔 어떤 이름으로 지어야 하나" 매번 고민하게 됐습니다.

해결: 리소스는 명사 복수형으로 통일하고([/users]), 동작은 HTTP 메서드로 구분하는 기본 원칙을 팀 문서로 정리했습니다. 이후로는 새 API를 만들 때 고민할 필요 없이 정해진 규칙만 따르면 됐습니다.

문제 2: 에러 응답 형식이 API마다 달랐다

어떤 API는 에러 메시지를 문자열로, 어떤 API는 객체로, 또 어떤 건 HTTP 상태 코드만 내려주는 식으로 제각각이었습니다. 프론트엔드에서 에러 처리 로직을 API마다 다르게 짜야 해서 불만이 나왔습니다.

해결: 전체 API에 공통으로 쓸 에러 응답 형식(에러 코드, 메시지, 상세 필드)을 정의하고, 공통 예외 처리 미들웨어를 만들어서 어떤 API든 같은 형식으로 에러가 내려가도록 통일했습니다.

문제 3: 한 번에 너무 많은 데이터를 내려주는 API를 만들었다

처음에는 "한 번의 호출로 다 가져오면 편하겠지"라는 생각으로 관련된 데이터를 전부 포함해서 응답을 만들었는데, 시간이 지나 데이터가 많아지면서 응답 속도가 눈에 띄게 느려졌습니다.

원인: 실제로는 프론트엔드에서 그 데이터의 일부만 쓰고 있었는데, 불필요한 데이터까지 매번 다 내려주고 있었던 것이 원인이었습니다.

해결: 꼭 필요한 최소한의 데이터만 기본으로 내려주고, 추가 정보가 필요하면 별도 파라미터나 API로 분리하는 방식으로 재설계했습니다. 페이지네이션도 이 시점에 함께 도입했습니다.

마무리하며

API 설계를 다시 정리하면서 느낀 건, 처음부터 완벽한 설계를 하기보다, 실제로 API를 쓰는 사람(프론트엔드 개발자)의 불편함을 계속 피드백 받으면서 다듬어가는 게 더 현실적이라는 점이었습니다. 이론으로 배운 REST 원칙은 방향을 잡는 데 도움이 됐지만, 실무에서는 팀 안에서 합의된 일관성이 더 중요했습니다.

API를 새로 설계하고 계신 분들이라면, 처음부터 완벽하게 만들려 하기보다 최소한의 일관성 있는 규칙부터 세우고 시작하시는 걸 추천합니다.