Development/API

REST API 사용 시 URL 구성 주의점

레오나르도 다빈츠 2021. 10. 14. 12:54

 

 

REST API의 HTTP methods는 GET, POST, DELETE, PUT 등 많은 종류가 있다.
예전 프로젝트에서는 이들의 차이점을 모른 채 GET, POST만 사용했었다.

잠시 잊고 있던 찰나, 오늘 유튜브 알고리즘에 유튜버 노마드 코더님의 영상이 추천됐다.
그리고 워스트 케이스에 내가 있어 충격을 받았고 다른 강의를 듣기 전에 미리 정리하고자 한다.

 

 

 

 



나는 지금까지 API를 구성하며, 이런식으로 이름 지었다.

- getUserInfo: 유저의 정보를 가져오는 API
- selectLessonInfo: 현재 레슨정보를 가져오는 API
- setUserInfo: 유저의 정보를 수정하는 API
- updateCoaching: 코칭 정보를 수정하는 API

 

그 당시엔 이런 네이밍이 직관적이라 생각했다.
이렇게 동사를 사용하거나 get, select 같이 비슷한 역할의 단어를 중구난방으로 사용하는 것은

협업을 할 때도, 유지보수 측면에서도 좋은 방법이 아니라고 한다.
이 말을 듣고 나니 오히려 의미를 파악할 때 시간적으로나 가독성으로나 비효율적이라 생각된다.

 

 

 

 

가독성있게, 협업하기 좋은 방법으로 구성하는 법은 이러하다.
첫번째. URL로 CRUD를 구분할 수 있도록 한다.
두번째. 엔드포인트에서 동사를 사용하지 않는다.

 


예를 들어 각각의 나라들과 그 나라의 관광지 정보를 CRUD하는 API를 만들어보자!

CASE 1.
GET /countrys: 전체 나라 목록을 가져온다.
POST /countrys: 새로운 나라를 생성한다.
== 이 때, 여기서 PUT이나 DELETE를 사용할 일은 없다. 왜냐면 이것을 통째로 없애지는 않으니까!

CASE 2.
GET /countrys/korea: 전체 나라 목록 중 한국에 대한 정보를 가져온다.
== 개 중에 하나를 가져올 때는 이렇게 포인트를 하나 더 생성해준다.

CASE 3.
DELETE /countrys/korea: 전체 나라 목록에서 한국의 정보를 삭제한다.
== 이름을 길게 지을 필요없이 그냥 methods만 변경해주면 된다.

CASE 4.
GET /countrys/korea/spot: 한국의 관광지 정보를 가져온다.
PUT /countrys/korea/spot: 한국의 관광지 목록에 추가한다.
DELETE /countrys/korea/spot: 한국의 관광지 목록에서 삭제한다.
== 이렇게 url은 동일하지만 methods만 달라도 역할이 달라진다.

CASE 5.
/countrys?code=AD012
/countrys?name=korea&page=5
== query parameter를 활용하여 새로운 url을 굳이 생성하지않고, pagenation도 가능하다.

 

 

 

 

이 영상을 보며 다른 자료들도 찾아보았는데, 다들 공통적으로 말하는 것이 있었다.

URL에 해당 API의 내용을 유추할 수 있는 get, update 같은 직관적인 단어사용을 피해야 한다는 것!

 

'좀 더 좋은 방향'을 고려하는 시야가 +1 되었다.