프로젝트에서 가게, 가게리뷰, 가게 좋아요 관련 CRUD를 만들때 api 경로에 대한 지적을 받았다.
REST API를 지켜야하는 이유는 RESTful API는 일관성 있는 디자인 원칙과 표준화된 방법을 따르기 때문에, 다른 개발자나 팀이 API를 이해하고 사용하기 쉽다.
따라서 일관성 있는 API 디자인은 코드의 가독성과 유지 보수성을 향상시키며 확장성과 유연성을 가진다.
나는 REST API를 공부했지만, 그에 맞지 않게 post, get, patch, delete만 나누어 주는 짓을 하고 있었다.
내가 작성한 REST API에 맞지 않는 api 경로
post /store 가게 생성
get /store/:storeUUID 가게 정보 가져오기
patch /store 가게 수정
delete /store/:storeUUID 가게 삭제
post /store/like 가게 좋아요
delete /store/like 가게 좋아요 취소
post /store/review 가게 리뷰 생성
patch /store/review 가게 리뷰 수정
delete /store/review 가게 리뷰 삭제
리소스 식별자를 포함시키자
patch /store
나는 우선, post와 patch는 무조건 body에 데이터를 모두 넣어야 하는 줄 알고, parameter 방식으로 넘기지 않았다. 하지만 이 방식은 요청의 특정 리소스를 명확하게 식별해주지 않는다.
patch /stores/:storeUUID
하지만 이렇게 바꾸어서 리소스 식별자를 URL 경로에 포함하면, 각 요청이 특정 리소스를 명확하게 식별할 수 있다.
API 경로는 다른 사람이 이해하기 쉽도록 작성하는 것이 좋다. 다른 개발자나 API를 사용하는 클라이언트들이 API를 이해하고 사용하기 쉽도록 명확하고 직관적인 경로를 제공하는 것이 중요하다.
이는 또한 API의 가독성과 유지 보수성을 향상시키는 데 도움이 된다.
document 이름으로는 단수명사, collection 이름으로는 복수 명사를 사용하자
patch /store/review
이런 표현은 store와 stores를 구분해주지 않았기 때문에 경로가 리소스의 컬렉션인지 개별 리소스인지를 명확하게 나타내지 않는다.
patch /stores/:storeUUID
하지만 stores라고 해준다면 stores collection의 단일 가게 document대한 수정 api라는 것을 명확하게 해줄 수 있다.
계층 구조 표현을 명확히 하자
post /store/review
가게의 review를 작성하는 api경로에서 단순히 store/review라고 작성해 주었다. 하지만 이는 review와 store에 대해 정확한 계층을 표현해주지 않는다.
또한 리소스 식별자를 포함시키지 않았고 단수/복수 형태로 구분해주지 않아, document인지 collection인지 알아보기가 힘들다.
patch /stores/:storeUUID/reviews/:storeReviewUUID
이렇게 바꾸어 주면 stores collection에 있는 “특정 가게 document의 reviews collection에 특정 리뷰 document를 수정해준다” 직관적으로 읽고 누구나 쉽게 알아볼 수 있다.
수정한 REST API에 맞지 않는 api 경로
post /store → post /stores 가게 생성
get /store/:storeUUID → get /stores/:storeUUID 가게 정보 가져오기
patch /store → patch /stores/:storeUUID 가게 수정
delete /store/:storeUUID → delete /stores/:storeUUID 가게 삭제
post /store/like → post /stores/like 가게 좋아요
delete /store/like → delete /stores/like 가게 좋아요 취소
post /store/review → post /stores/:storeUUID/review 가게 리뷰 생성
patch /store/review → patch /stores/:storeUUID/reviews/:storeReviewUUID 가게 리뷰 수정
delete /store/review → delete /stores/:storeUUID/reviews/:storeReviewUUID 가게 리뷰 삭제
