REST API 사용 시 URL 구성 주의점

 

 

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 되었다.