Restful API 설계

 

 
 
 
우리가 작성하려고 하는 서비스 API가 어떻게 구현될 것인지 미리 정의를 내리고 진행해 보도록 하자.
 
 
우리는 이번 강의를 통해 사용자(users) 관리 API, 그리고 그 사용자가 작성하는 게시글(posts)에 대한 REST API를 개발하려 함. 일반적으로 사용자와 사용자가 작성하는 게시글의 관계는 한 명의 사용자가 여러 개의 게시글을 작성할 수 있다고 정의내릴 것임. 이러한 상황일 때 사용자와 게시글의 관계를 1:N이라 함.
 
 
우리가 설계할 API는 크게 조회, 생성, 삭제와 관련된 기능이 있을 것임. IT 개발에서는 서비스에 사용되는 기능을 구현하는 데 있어서 스토리지에 작업을 어떻게 하는지에 따라 크게 데이터의 생성(CREATE), 조회(READ), 수정(UPDATE), 삭제(DELETE)로 구분함. 이러한 기능들은 간단하게 단어 각각의 앞 글자를 따서 CRUD라고 하기도. IT 서비스에서 특정한 비즈니스 로직을 구현함에 있어서 CRUD라는 기능이 있다는 건 Database 또는 스토리지에 어떠한 작업을 추가하고 읽어들이고 변경하고 삭제하는 기능이 있다고 생각하면 좋을 듯.
 
 
 

	Description	REST API	HTTP Method
(1)	Retrieve all Users	/users	GET
(2)	Create a User	/users	POST
(3)	Retrieve one User	/users/{id}	GET
(4)	Delete a User	/users/{id}	DELETE
(5)	Retrieve all posts for a User	/users/{id}/posts	GET
(6)	Create a posts for a User	/users/{id}/posts	POST
(7)	Retrieve details of a User	/users/{id}/posts/{post_id}	GET

 
 
(1) 먼저 사용자에 대한 부분과 게시글에 대한 부분으로 나누어 정리해 보려 함. 사용자 목록 조회를 위해서는  /users 라는 URI(또는 Endpoint)를 사용할 것임.  /users 라는 Endpoint는 HTTP의 GET이라는 Method로 요청될 것임. 현재 저장된 전체 사용자의 목록을 반환하도록 하는 기능이 될 것.
 
(2) 다음으로 사용자를 등록하기 위한 Endpoint를 정의할 건데 이 또한  /users 라고 이름지을 것이지만 이 경우에는 HTTP Method를 POST로 요청할 것임. 이전의 전체 사용자 목록 조회(1)와 지금의 새로운 사용자 추가(2) 두 API가 같은 URI를 가지고 있지만 HTTP Method가 서로 다르기 때문에 하나의 URI를 가지고도 두 가지 기능을 할 수 있다는 것을 알 수 있음.
 
이렇게 REST API 설계 시 적은 Endpoint를 가지고 HTTP Method를 다양하게 함으로써 여러 API를 설계할 수 있음. (1), (2)와 마찬가지로 (3), (4) 역시 같은 URI를 가지게 되는데 (3)은 상세 보기, (4)는 삭제라는 기능을 가짐. 대신 HTTP Method를 상세 보기는 GET, 삭제는 DELETE로 구분하는 것. 이들의 경우 전체 사용자 목록 중 특정 누군가를 지정해서 해당 사용자를 상세 보기하거나 삭제하는 기능을 가지게 되는데 이렇게 전체 전체 사용자 목록을 뜻하는  /users  뒤에  /{id}  , 즉 id 값을 가변 데이터로 지정해 줌으로써 전체 목록에서 어떠한 사용자의 상세 보기 또는 삭제라는 의미로 URI를 지정하도록 하겠음.
 
다음으로 게시글의 경우에도 사용자 상세 보기 때와 마찬가지로  /users/{id}  뒤에   /posts 를 추가함. 앞서 우리는 한 명의 사용자가 여러 게시글을 작성할 수 있기 때문에 사용자와 게시글의 관계는 1:N이라고 하였음. 따라서  /users/{id} /posts 를 그대로 해석해 보면, 전체 사용자 목록 중에서 특정한 사용자가 가지고 있는 게시글의 목록이라고 할 수 있음(5). 또는 그 사용자의 게시글 목록에 특정한 데이터를 작성하는 기능인 것(6).
 
마지막의  /users/{id}/posts/{post_id} 는 전체 사용자 목록 중 특정 사용자의 게시글들 중에서 특정 게시글의 ID를 지정했기 때문에 게시글의 상세 보기로 세분화시켜 볼 수 있음(7).
 
 
 
총 7개의 API가 나왔지만 결국 사용된 URI는 4개( /users ,  /users/{id} ,  /users/{id}/posts ,  /users/{id}/posts/{post_id} )로, 각각의 HTTP Method를 혼합해 사용해 줌으로써 보다 다양한 API를 사용할 수 있도록 만들어 줌.
 
이러한 방식은 앞서 말한 것처럼 REST API가 가지고 있는 장점 중 하나로 REST API 설계 시 체계적이고 효율적이면서 확장성 있게 설계하는 것이 필요함.
 
 
 
 
 
출처
본 포스트는 인프런 이도원 강사님의 "Spring Boot 3.x 를 이용한 RESTful Web Services 개발" 강의를 통해 직접 작성 및 정리한 글입니다.