API URI 설계에 대한 고민

참고할만 문서 : API 디자인 지침 - Best practices for cloud applications | Microsoft Docs

 

 

URI 설계 도중 고민거리가 생겼다.

 

Q. 여러 회사가 있을 때 "회사에 소속된 팀 조회" & "회사에 소속된 사원 조회" 를 하는 api를 만들 경우 

 

1.

/회사/{id}/팀

/회사/{id}/멤버

2.

/팀?회사id=1

/멤버?회사id=1

 

나는 1번이 맞다고 생각했으나, 더많은 정보가 있을 때

/회사/{id}/장비

/팀/{id}/멤버

등 api 개수가 너무 많아지는 문제가 있다고 생각되었다.

 

2번의 경우도 더많은 검색조건 경우의 수가 생기기에

/멤버?회사id=1&팀id=2&성별=남

처럼 하나의 uri 컨트롤러가 너무 많은 기능을 담당하게 되는 문제가 있다고 생각되었다.

 

그래서 인프런의 김영한님께 의견을 여쭸는데 감사하게도 답변을 주셨다.

 

A.

설계에 대한 모든 것은 트레이드 오프가 있습니다.

 

/회사/{id}/팀/{id} 처럼 설계를 해도 되고,

/팀/{id} 처럼 줄여서 설계를 해도 됩니다.

 

URI에서 중요한 것은 리소스를 식별하는 것 입니다.

리소스를 확실하게 식별할 수 있으면 되는 것이지요.

여기서 리소스가 팀, 사원이기 때문에 다음과 같이 설계하셔도 됩니다.

 

/팀

/팀/{팀Id}

/사원

/사원/{사원Id}

 

대신 이 경우 팀과 사원의 ID가 다른 회사들과 겹치지 않도록 구분할 수 있어야 합니다.

만약 구분할 수 없다면 다음과 같이 정리하는 것이 좋습니다.

/회사/{id}/팀/{팀id}

추가로 마지막에 고민하셨던 이 내용은

/멤버?회사id=1&팀id=2&성별=남

하나의 URI가 너무 많은 기능을 담당하게 되는 문제가 있다고 고민했지만, 사실 이것은 하나의 기능만 담당하고 있습니다. 바로 멤버를 검색하는 기능만 담당하고 있는 것이지요. 이렇게 검색 조건이 추가로 더 들어가는 것은 괜찮습니다.

 

----------------------------------------------------------------

즉 답변을 정리하자면

 

1. 핵심은 리소스의 구별이다.

 

회사A의 팀id와 회사B의 팀id 의 값이 겹쳐서 회사가 없이 팀을 구분할 수 없다면

/회사/{id}/팀/{id} 

같은 설계가 필요하다.

그렇지 않다면

팀/{id}

로 가능하다.

 

2. 하나의 URI에 너무 많은 기능이 있다? - 전부 같은 목적을 지닌 1가지 기능이다.

- 하나의 URI가 너무 많은 기능을 담당하게 되는 문제가 있다고 고민했지만, 사실 이것은 하나의 기능만 담당하고 있다. 바로 멤버를 검색하는 기능만 담당하고 있는 것. 이렇게 검색 조건이 추가로 더 들어가는 것은 괜찮다.