• 목차
  • 1. 기존 API path 살펴보기
  • 2. http 메소드 활용하기
  • 3. REST API 디자인 가이드
  • 4. path parameter vs query string

  
  

REST API. 지난 기록에도 있는 개발에서 절대 빠질수 없는 것이다.
REST API에 대한 내용은 [WEB] REST 란 무엇일까 해당 포스팅에 자세히 설명했으니 생략하고 오늘은 movester의 api를 restful 한 api로 변경하는 과정을 알아보자.

1. 기존 API path 살펴보기

시작에 앞서 먼저 반성부터 하고 가자.
REST API를 만들겠다는 나의 초기 다짐과는 무색하게 나는 전혀..! REST API를 만들고 있지 않았다.
지금까지 사용했던 수정 전 api path를 보자

// notice
router.post("/notice/create", noticeCtrl.noticeCreate);
router.get("/notice/list", noticeCtrl.noticeList);
router.post("/notice/detail", noticeCtrl.noticeDetail);
router.post("/notice/update", noticeCtrl.noticeUpdate);
router.post("/notice/delete", noticeCtrl.noticeDelete);

// faq
router.post("/faq/create", faqCtrl.faqCreate);
router.get("/faq/list", faqCtrl.faqList);
router.post("/faq/detail", faqCtrl.faqDetail);
router.post("/faq/update", faqCtrl.faqUpdate);
router.post("/faq/delete", faqCtrl.faqDelete);

공지사항과 자주묻는질문 게시판과 관련된 api path들이다.
학부생 시절 했던 프로젝트의 path를 아무 생각없이 그대로 쓰고 있었다.
생성할 땐 create, 특정 하나만 볼 땐 deatil, 전체를 구할 땐 list…
url 만 보고 데이터 리소스를 바로 알 수 있도록 하자는 REST API와는 맞지 않는다.
왜냐…! http 메소드가 get 과 post 로만 이루어져있기 때문이다.
REST API는 애당초 http 메소드 (get, post, put, patch, delete)를 통해 필요한 데이터 리소스를 파악하자는 데서 시작된 것이다.

멍청했던 나는… path에 특정 id 가 붙으면 (query string) post, 아니면 get으로 구현하고 있었다.😭
그래도 이제서야라도 깨달은 것을 감사히 여기며 오늘은 나의 REST API 규칙을 정하고, 그 규칙에 맞게 수정해나가도록 하자.

2. http 메소드 활용하기

위의 notice를 기준 삼아 http 메소드의 적절한 사용처를 알아보자.

어느 부분이 중점적으로 변했는지 보이는가?
우선, GET/POST 만 사용하던 http 메소드를 더 맞는 상황에 맞게 다양하게 사용했다.
메소드를 적절하게 사용한 덕분에 url에서 동사로 설명해주던 create, update, list, detail, delete가 변경된 url에서는 필요가 없어졌다.
또한 기존 notice가 notices로 복수형이 되었는데 이 이유는 아래에서 설명하겠다.
RESTful 한 API로 변경하면서 조금 더 http 메소드를 활용하며 데이터 리소스 관계가 명확해진 것을 볼 수 있다.

내가 놓쳤던 부분은 url 이 페이지 중심이 아닌 자원(데이터) 중심이었어야 했다는 점!

나는 이 페이지가 무슨 일을 하는가에 중점을 두고 path를 작성하고 있었던 것이다.
반성하자😭😭

3. REST API 디자인 가이드

1) 심플하고 직관적으로 하기.

행위 표현을 하지 말자는 것과 비슷한 의미같다. (내 예전코드의 create, update 등등)

2) 동사보다는 명사를 활용하기.

POST /api/setNotices 보다는 POST /api/notices 로 의미를 http 메소드로 파악하게끔 하자

3) 단수보다는 복수를 사용하기.

notice > notices 로 변경하기!

4) _ (underbar) 대신 - (dash) 사용하기.

5) url에는 소문자만 사용하기.

serviceCenter 처럼 카멜케이스로 구분하던 것들을 4, 5번의 이유 때문에 service-center로 변경하였다.

6) 마지막에 / 사용하지 말기.

4. path parameter vs query string

나는 수정 전에는 POST를 사용한 것은 전부 query string으로 받아왔다.
하지만 수정된 url에서는 path parameter인 것을 볼 수 있을 것이다.
이 둘은 api가 사용되는 목적에 따라 구별되어야 한다.

• path parameter : 별도로 정제되지 않은 데이터를 가져올 때 (모든 리스트 조회, 특정 id 조회)
• query string : 별도로 정제한 데이터를 가져올 때 (filter, sort, search)

게시판에 관련된 api에서는 모두 정제되지 않은 데이터가 필요했기에 path 를 사용했다.
스트레칭 목록을 filter해와서 조회할 때는 query string 을 활용해야 할 것이다!

다음에는 status code를 수정하는 과정도 함께 알아보도록 하자!