REST 원칙을 지키며 API를 설계하자

재능없는 개발자·2023년 5월 27일
0

프로젝트에서 가게, 가게리뷰, 가게 좋아요 관련 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 /storepost /stores 가게 생성

get /store/:storeUUIDget /stores/:storeUUID 가게 정보 가져오기

patch /storepatch /stores/:storeUUID 가게 수정

delete /store/:storeUUIDdelete /stores/:storeUUID 가게 삭제

post /store/likepost /stores/like 가게 좋아요

delete /store/likedelete /stores/like 가게 좋아요 취소

post /store/reviewpost /stores/:storeUUID/review 가게 리뷰 생성

patch /store/reviewpatch /stores/:storeUUID/reviews/:storeReviewUUID 가게 리뷰 수정

delete /store/reviewdelete /stores/:storeUUID/reviews/:storeReviewUUID 가게 리뷰 삭제

profile
https://www.youtube.com/watch?v=__9qLP846JE

0개의 댓글