배달 주문을 관리하는 어플리케이션의 API 명세서를 작성하는 연습을 하는데 궁금점이 생겼다.
회원가입 관련된 API 단계에서
1. 일반 고객의 회원가입, 가게 주인의 회원가입, 관리자 회원가입 이렇게 따로 나눠서 관리해야될지에 대한 고민이었는데
2. 일반 고객, 가게 주인, 관리자를 하나의 API로 묶어서 관리해야할지
우선, 설계하는 의도에 따라서 달라질 수 있다고 생각했다.
1번 의도대로 설계한다면 각각의 회원 유형에 따라서 회원가입 시 필요한 정보가 다르므로 요청할 데이터를 따로 구분하지 않아도 된다는 이점이 있지만
2번 의도대로 설계하면 메서드를 따로 분류하지 않아도 되기 때문에 회원가입, 회원 정보 수정, 회원 탈퇴 등 여러가지로 나눠지는 중복되는 코드의 양을 줄일 수 있다.
종합적으로 본다면 일단 관리자는 따로 분리하고,
일반 고객과 가게 주인은 둘의 요구되는 중복되지 않는 정보가 많다면 분리, 차이가 크지 않다면 하나로 묶는 것이 효율적이라 판단되었다.
지금까지 api 명세서를 작성할 때 Method, URL, Request, Response를 나누어서 작성을 했었다.
그래서 Path Variables 형태로 작성을 했었는데
URL Path : 자원의 위치를 명확하게 식별하기 위해 사용된다.
상품의 목록 조회(Path Variables) :/stores/{storeId}/products
이번 연습에서는 Request와 Response를 생략하기로 하였기 때문에 url을 Query Parameter 형태로 작성해보기로 하였다.
Query Parameter 형태는 동작(수정, 삭제 등)에 대한 명령어(update, delete, hidden 등)는 URL에 유지하면서, 주요 자원 식별자는 Query Parameter로 전달하는 형태로 표현한다.
Query Parameter : 선택적인 요청 옵션(페이징, 정렬, 필터링 등)을 전달하기 위해 사용된다.
상품의 목록 조회(Query Parameter) :/stores/products?store_id={storeId}&page={page}&size={size}
일반적으로 RESTful API 설계에서는 자원 식별을 URL 경로를 통해 처리하고, 요청의 세부 옵션을 Query Parameter를 통해 처리하는 방식이 선호된다.
