RESTful API URL 설계

응용 프로그램 간에 데이터를 주고 받는 방법이자 표현에 대한 약속

/{version}/{resource-name}/{id}/{additional-verb}
/v1.0/keywords/1/stat

버전 관리

v{major}.{minor} : v1.0 <-> v1.2 -> v2.0
major : 이전 버전과 호환되지 않는 수준의 변경
minor : 호환 가능한 수준의 변경

자원 명

복수형 자원 명

식별자

id, name 등 식별할 수 있는 고유의 값

추가적 동사

이 부분이 참 어렵다.. 생각을 많이하게 되는 부분이고
가이드 라인을 만들었을 때 지키기 어렵게 만드는 부분이다.
자원의 범위를 지정하면서 기능을 확장하다 보면 API의 자원 범위에 따라
요청에 필요하지 않은 부분까지 응답해야하는 구조가 생기기 마련이다.

인터페이스를 세분화하면 그만큼 요청에 대한 양식이 많아지고,
통합하게 된다면 불필요한 응답까지 내려가야한다.

전체 메뉴 조회
/api/v1.0/menus
메뉴 ID로 조회
/api/v1.0/menus/1

까지는 되게 평범하다 전체조회할건지 식별자로 조회할 건지,

/{version}/{resource-name}/{id} 까지의 약속, 가이드라인은 지키기 쉬운데
추가 기능을 만들 때 그 가이드를 지키기는 쉽지 않은 것 같다.

이 메뉴 API는 계층적 구조를 가지고 있어서 부모와, 자식 노드의 계층 표현을 하는 응답을 해줘야 한다.
Lazy Loading에 대한 대응이 필요하다. 부모 노드에 대한 자식 계층만 가져와야한다.
이런 요구사항들이 생기기 시작하면 어떻게 풀어나갈 것인가?

/api/v1.0/menus/1?depth={depth}
/api/v1.0/menus/1:node?depth=2
/api/v1.0/menus/1/hierarchies?depth=2
/api/v1.0/menus/게시판

{id} 식별자 값을 Number로 자기 자신만,String은 아래 하위 메뉴까지 가져오게 할 것인가

이것저것 고민하다보면 API URL 설계 때문에 시간을 잡아먹기도 한다.

팀원들과 조직에서 가이드라인을 지키는데 큰 비용을 들이지 않고 이해할 수 있는 규칙을 보완해나가야

좋은 RESTful API가 되지 않을까?

참고

🐶같이 코딩