앞 포스트에서는 RESTful한 API의 중요성을 다루었다면
REST API의 구성 요소를 어떻게 설계를 하면 조금더 RESTful 할까요?
기본적으로는 REST API는 기본적으로 HTTP 통신 규약에 따라 신호를 전송합니다.
[https://velog.io/@jung2one/T.I.L-Today-I-Learnt-How-the-Web-works](Web HTTP 형식 포스트)
REST API의 CRUD 기능
그러기 때문에 CRUD 기능을 REST에서도 사용합니다. 그중에
Create -> POST
Read -> GET
Update -> PUT,PATCH
Delete -> Delete
매소드를 사용합니다. 그중에 POST, PUT, PATCH는 body를 통해 조금더 많은 내용과 감추어져서 통신이 가능하다는 장점이 있습니다.
POST
어떠한 정보를 전달하거나 입력하고자 할때 사용됩니다.
POST https://(도메인 주소)/products/foods/drinks위와 같은 uri 주소를 사용하면 제품 중 음식 카테고리에 음료라는 데이터베이스에 접근하고 싶다는 것을 알수 있습니다. POST method를 사용하면 앞서 언급한 것과 같이 Body에 새로 등록하고 싶은 음료 제품의 정보를 담아 저장하는 기능을 수행합니다.
GET
어떠한 정보를 불러 올때 사용됩니다. 특정 제품의 목록이나 상세 정보를 불러올때 사용됩니다.
1) GET https://(도메인 주소)/products/foodslist
2) GET https://(도메인 주소)/products/foods/drinks/21번 URI같은 경우에는 제품의 음식 목록을 불러오며
2번 URI같은 경우에는 음식 카테고리의 음료 제품들 중 2번 id에 대한 정보를 불러오기 위한 URI입니다.
Update
업데이트 같은 경우 기능을 수행하는 명령어중 PUT과 PATCH 두가지가 사용됩니다. 사실 두개 모두 같은 기능을 수행하지만 무언의 약속처럼 PUT은 어떠한 데이터를 통체로 바꿀때(예: 정지원이라는 유저 전체를 업데이트) 사용되고 PATCH는 데이터 덩어리의 일부만 바꿀때(예: 정지원이라는 유저의 닉네임 업데이트) 사용 됩니다.
Delete
삭제라는 동작 또한 정확한 정보나 기능을 명시함으로서 해당 정보에 접근하여 삭제를 합니다.
업데이트와 같이 사실 모든 명령어로 서로의 기능 수행이 가능하지만 이 기능들을 조금더 가시적으로 표현하기 위해 나눈 것입니다.
RESTful한 API의 설계
위에서 보여준 URI는 사실 엄청 간단하고 RESTful하지 못합니다. 조금더 RESTful하게 만들기 위해서는 몇가지 규칙이 있습니다. 제가 실제 프로젝트를 진행하면서 느끼고 개인적 견해만 여기서 작성을 하고 나머지 규칙은 "restful api design guidelines" 검색을 통해 조금더 자세하게 찾아 볼수가 있습니다.
1. 동사가 아닌 명사로 이루어 질 것
CRUD라는 기능을 수행하기 위한 명령어를 통해 POST, GET, PUT, PATCH, DELETE를 명시 해주었기 때문에 추가적인 동사를 URI에 포함 시킨다면 중복되어 효율적이지 못한 URI가 될수도 있고 자칫하다 기능이 상충되는 이름이 정의 될수가 있습니다. 더 나아가 메소드의 구분을 통해 하나의 URI로 다양한 기능을 수행할수 있는 가능성을 막을 수도 있습니다. 그렇기 때문에 항상 명사로 이루어져야합니다.
POST https://(도메인 주소)/products/foods/drinks/newdrinkcreate (x)
#이미 POST로 기능이 명시 되어있다.
POST https://(도메인 주소)/products/foods/drinks
#이와 같이 URI를 설계하면 POST를 통해 새로운 음료 정보를 저장할 수도 있지만
GET https://(도메인 주소)/products/foods/drinks
#GET메소드를 사용하여 특정 음료를 지정, 혹은 전체 음료의 리스트를 접근할수가 있다.2. 기능을 수행하는 View의 클라스 이름, 상세하게 명시하기
보통 URI를 만들때 기능에 따라 만들기 때문에 특정 기능을 수행하는 로직의 class명을 사용합니다.
제품의 상세페이지를 나열하는 로직인 ProductDetailListView가 있다면 아마 URI에는 이러한 이름이 어딘가에는 포함이 되는 것이 이상적입니다. 그렇기 때문에 View의 이름도, 포함하는 URI도 수행하는 기능이나 목적에 맞게 명확하게 설정할 필요가 있다고 생각합니다.
3. PATH PRAMETER, QUERY PARAMETER
사실상 RESTful API에서 가장 중요한 부분을 차지한다고 생각합니다. 그 웹페이지나 앱에서 정말 독립적인 기능을 수행하는 회원가입 또는 로그인 페이지 등등이 아닌 특정 지정값에 따라 같은 기능을 수행하지만 데이터가 바뀌는 API가 있습니다. 예를 들어 category별 제품의 리스트라던가, User에 따른 profile 정보라던가 일일이 특정 카테고리별 혹은 유저별로 URI를 만들수가 없습니다. 그래서 parameter라는 뜻과 같이 URI에 변수를 삽입하는 과정입니다.
* PATH PARAMETER
PATH는 경로라는 말과 같이 특정 경로를 입력해줍니다. 보통 대분류나 이 값이 명확할 때 사용이 됩니다.
GET https://(도메인 주소)/products/2/drinks
^ ^숫자 2와 drinks 모두 path parameter입니다. 숫자는 Food category의 id값인 2, drinks는 food 카테고리 속 음료라는 sub카테고리 입니다. 보이는 것과 같이 int, str든 다양한 방식으로 지정이 가능합니다. 언제든 category의 id값은 바뀔수 있고 sub category의 이름도 바뀌어 다른 정보에 접근 할수가 있습니다.
하지만 PATH 하나로 어디에 접근하기 위한 URI인지 쉽게 파악하기가 힘듭니다. Products의 2가 제품의 카테고리를 의미하는것인지 아니면 2번째 제품을 의미하는지, 2번 카테고리의 음료는 서브카테고리인지 아니면 그냥 2번 카테고리속 제품의 이름이 drinks인지 구별하기가 힘듭니다. 그래서 명확한 경우 아니면 PATH보다는 Query Parameter가 더 직관적인 URI 설계를 할수가 있습니다.
* QUERY PARAMETER
Query라는 뜻과 같이 질문에 대한 변수값을 지정합니다.
윗 제품에 대한 음식 카테고리에 대한 음료를 Query Params로 표현하면 아래와 같습니다.
GET https://(도메인 주소)/products?categoryId=2&subcategory=drinksquery문이 시작 됨을 알리는 "?" 기호 이후 어떠한 질문, 즉 catergoryId 그리고 subcategory를 지정하는 것입니다. 윗 PATH보다 조금더 직관적이고 추론하기 쉽습니다.
물론 기능을 구현할때 어떠한 Query문을 사용할지, int값을 답할지 str값으로 답할지 규칙을 정해야합니다. 하지만 변수명을 지정해줌으로서 직관적으로 URI의 기능을 짐작할수가 있습니다.
또한 "&" 다양한 Query문을 연관시켜 보다 detail한 요청문을 만들수도 있습니다.
