RESTful API를 설계하기 위한 디자인 팁

스포카에서 발행한 RESTful API를 설계하기 위한 디자인 팁

올라왔었던 REST 아키텍처를 훌륭하게 적용하기 위한 몇 가지 디자인 팁의 글에서 언급되지 않았던 추가적인 내용에 대해서 좀 더 얘기해보고자 합니다. 혹시 이전 포스팅을 읽지 않으셨다면 이전 포스팅을 먼저 읽으신 후 이 포스팅을 읽어주시기 바랍니다.

컬렉션에 관해서는 앞서 소개한 이전 글에서 자세히 설명해놓았으니 읽어보시기 바랍니다. 지금 제가 언급할 것을 도큐먼트인데요. 도큐먼트는 컬렉션과는 달리 단수명사나 명사의 조합으로 표현되어 URI에 나타납니다.

위의 예제에서 leauges라는 컬렉션 리소스가 있는 것을 알 수 있습니다. 그 컬렉션의 자식 리소스 중 하나가 seattle이라는 리소스인데요, 바로 이 리소스가 도큐먼트입니다. 도큐먼트는 하위 계층으로 또 컬렉션을 가질 수 있습니다. 이 예제에서의 teams가 seattle의 자식 컬렉션 리소스가 되겠지요. 즉, 단수 리소스는 도큐먼트라 칭하고 복수 리소스는 컬렉션으로 칭한다고 알아두시면 됩니다.

이 URI는 또한 문서의 계층 구조를 표현하고 있습니다. 즉 슬래시 기호(/) 다음으로 나타내는 명사가 그 앞에 나오는 명사의 자식 계층이 되는 것이지요. 이러한 도큐먼트의 응답으로써, 요청에서 명시된 Content-Type 헤더에 1:1대응하는 응답을 주는 것이 의미 있을 때가 있습니다. 가령,

이와 같은 URI에 3개의 요청이 주어졌고, 각각 Content-Type이 다음과 같을 때 어떤 응답이 보내져야 할까요? 물론, 그것은 응답을 설계한 사람의 맘이지만 일반적인 기준을 적용해본다면 1번과 2번 요청에는 각각 json, xml 형식으로 구조화된 데이터가 그리고 3번 요청에 대해서는 해당 강아지의 사진이 담긴 png 파일을 보낼 수 있을 것입니다. 또한, Content-Type에 대해서 명시하여 원하는 리소스를 선택할 수 있으므로 URI 내에는 파일 확장자를 포함하지 않는 것이 좋습니다.

어째서 파일에 확장자를 붙이지 않는 것이 더 나은 선택일까요? URI는 고유한 리소스를 나타내는 데 쓰여야 합니다. 그런데 URI에 확장자를 붙이는 순간 마치 다른 리소스인 것처럼 느껴집니다. 확장자를 달리하여 같은 리소스에 대한 다른 표현 양식을 주문하는 것이지 해당 리소스가 달라지는 것은 아닙니다. 또한, URI에 직접 확장자가 붙게 되면 해당 리소스 URI가 응답으로 지원하는 확장자만큼 새로운 URI들이 생기게 되겠지요. 결코, 이것은 좋은 디자인이 아닙니다.

기본으로 GET, PUT, POST, DELETE 요청에 1:1매치 되는 개념인 CRUD가 있습니다. CRUD의 앞글자들을 풀어보면 Create, Read, Update, Delete가 될 텐데, 각각 POST, GET, PUT, DELETE에 대응되는 개념입니다. 그런데 사실 URI를 디자인 하다 보면 이러한 방식으로 나타내기 참 어려운 경우를 많이 만나게 됩니다. 그 중 가장 많은 경우가 어떤 특정한 행위를 요청하는 경우입니다. 많은 분이 이럴 때 동사를 쓰는데, 앞선 포스팅에서 밝혔듯이 동사를 써서 URI를 디자인하는 것은 대체로 옳지 않은 방식으로 여겨집니다.

이럴 때 컨트롤러 리소스를 정의하여 이 문제를 해결할 수 있습니다. 컨트롤러 리소스는 URI 경로의 제일 마지막 부분에 동사의 형태로 표시되어 해당 URI를 통해 접근했을 때 일어날 행위를 생성합니다. (개념적으로는 이렇게 받아들이시면 됩니다.) 생성과 관련된 요청이 POST이기 때문에 컨트롤러 리소스에 접근하려면 POST 요청을 보내야 합니다. 예제를 살펴보시면 이해하기 빠르실 겁니다.

그리고 마치 프로그램의 함수처럼 컨트롤러 리소스에는 입력값을 전달할 수 있습니다. 그것은 POST 요청의 엔티티 바디에 포함되어야 합니다. 그리고 역시 함수에서 반환값을 돌려주듯이 컨트롤러 리소스에서는 해당 입력 값에 대한 응답 값을 돌려주면 되겠습니다.

흔히 GET 요청을 보낼 때 뒤에 추가로 쿼리 스트링(?,=,& 기호를 이용하여)을 전달하곤 합니다. 여기서는 그 쿼리 스트링을 어떻게 디자인 하는 게 좋은지에 대한 논의와 함께 실제 서비스에서 사용되는 사례를 살펴봅니다.

...

더 읽어보러 가기

직군 정보
웹 프론트엔드

기업 문화 정보


기술 스택 정보

더 많은 내용은 더팀스에서 확인하세요!