REST API URI 패턴

REST URI는 심플하고 직관적이게 작성

REST API는 기본적으로 외부의 시스템과 리소스 교환을 위해 만들어지기 때문에 다른 사람이 사용하기에 어려움이 없고 직관적으로 이해할 수 있어야 한다. Depth를 깊게 만들어 복잡하게 만들기보단 최대 2 Depth를 유지하며 만드는 것이 이해가 편하다.

• /users
• /users/boards

URI에 리소스명은 명사를 사용하도록 한다.

REST API는 리소스에 대해서 행동을 정의하는 형태를 사용한다.

• POST : /users
• GET : /users
• GET : /users/{userId}

위에 예시를 보면 /users 리소스를 생성하라, /users 리소스의 전체 목록을 가져와라, /users 리소스를 {userId}를 통해 검색해서 가져와라 라는 의미로, HTTP Method에 의해 CRUD(생성, 읽기, 수정, 삭제)의 대상이 되는 개체(명사)여야 한다.

• POST : /getUsers
• POST : /setUsersAddress

위와 같이 행위를 POST로 정의하지 않고 get, set 등의 행위를 URL에 붙인 경우가 잘못된 예시이다. 위의 잘못된 예시를 바로하면 아래와 같다.

• GET : /users
• POST : /users/{userId}/address/{address}

또한, 의미상 단수형 명사(user, dog, cat)를 사용하기 보다는 복수형 명사(users, dogs, cats)를 사용하는 것이 의미상 표현하기 더 좋다.

 

일반적으로 권고되는 설계는 아래와 같다.

Resources	POST	GET	PUT	DELETE
-	생성	검색	수정	삭제
/users	새로운 users 등록	users 전체 목록 검색	다수의 users 수정	다수의 users 삭제
/users/{usersId}	-	{usersId}를 가진 users 검색	{users}를 가진 users 정보 수정	{users}를 가진 users 정보 삭제

 

Resource 간 관계를 표현하는 방법

REST 리소스는 서로 관계가 있을 수가 있다. 예를 들어 사용자가 작성한 게시글이나 사용자의 주소가 예로 들 수가 있는데, 사용자-게시글, 사용자-주소와 같은 각각의 리소스 관계를 표현하는 여러 방법이 있다.

 

1.서브 리소스로 표현하는 방법

ex) /resources/{resourcesId}/anotherresources

사용자가 작성한 게시글 목록을 검색하는 API를 표현해보자.

• GET : /users/{userId}/boards

위와 같이 {userId}를 가진 사용자가 작성한 게시글 목록을 반환하는 API를 표현할 수 있다.

2. 서브 리소스에 관계를 명시하는 방법

리소스 간의 관계가 복잡한 관계라면 '관계'에 대해 명시적으로 표현하는 방법이 있다.

심플하게 이전의 예시를 가져와 표현을 해보자면

• GET : users/{usersId}/writes/boards

위와 같이 표현될 수 있다.

 

두 방법 모두 용도에 맞게 사용하면 된다. 하지만 첫번째 예시의 경우 일반적으로 소유 'has'의 관계를 묵시적으로 표현할 때 용의하며 두번째의 경우 관계가 애매하거나 구체적인 표현이 필요할 때 사용한다.