BEST PRACTICE FOR REST API DESIGN - URI편
최근에..
최근 express를 활용한 개인 프로젝트가 진행 중에 있다.
3주 전에는 플라스크로 내 인생의 첫 API를 만들었었지만, 그때는 강의를 많이 참고했었고 URL을 헷갈리지만 않게 짜는 것에 포커스를 뒀었다.
이번 express 프로젝트에서 Routing이라는 개념을 새로 배웠다.
Routing(라우팅)이란?
클라이언트의 요청(URI, METHOD)에 애플리케이션이 응답하는 방법을 결정하는 것을 말한다.
쉽게 말해서, 특정 URL을 특정 METHOD로 받았을때 어떤 응답을 어떻게 처리해서 보내줄지 정해주는 행위이다.
결국 플라스크로 API를 만들어 왔던것도 전부 Routing이라고 볼 수 있겠다.
깔끔한 URL의 필요성
express에서는 연관이 있는 라우터끼리 같은 파일에 묶어서 분리해서 관리할 수가 있는데, 이렇게 분리해서 관리해주기 때문에 사전에 URL분배(?)계획을 잘 세워놓지 않으면 헷갈리겠다는 직감이 왔다.
분명 '클린코드' 처럼 URL을 결정하는 규칙 또한 암암리에 정해져 있을거라 생각했다.
구글링을 했더니 실제로 'Best Practice for REST API Design'이라는 표준처럼 쓸 수 있는 규칙이 있었다.
여러가지 글들을 참고해서 공부한 내용들을 아주 간략하게 정리해보고자 한다.
(편의상 URL과 URI를 엄밀하게 구분지어서 사용하지는 않겠습니다. 같은거라고 생각해주세요.)
키워드
1) 자원(RESOURCE) - URI
2) 행위(Verb) - HTTP METHOD
3) 표현(Representations)
1. URI에는 정보의 자원만 표현, 행위는 METHOD로 설명!
쉽게 말하면 URL에 동사를 넣지 말고, 명사로만 구성하라는 것이다.
아래는 내가 실제로 프로젝트 중에 사용했던 URL이다.
GET /article/load-all-articles (BAD👿)load라는 명사가 들어가있다.
하지만 데이터를 받아온다는 의미에서 GET으로도 충분히 설명이 된다.
수정해보자.
GET /article/all-articles (GOOD😻)2. 자원의 구분 : Collection과 Document
Document : 문서, 한 객체
Collection : Document들의 집합
아래 URI는 fruits라는 Collection과 mango라는 Document로 이루어져있다.
https://coffeed-cat.com/fruits/mango아래는 다른 예시이다.
https://coffeed-cat.com/fruits/mango/countries/india여기서
Collection은 fruits와 countries이고
Document는 mango와 india이다.
추가적으로 Collection은 복수형, Document는 단수형으로 적어주면 더욱 직관적인 URI가 된다.
이것을 바탕으로 나의 코드를 수정해보겠다.
/articles이렇게 간단해졌다.
3. 그 외 여러가지 규칙들
3-1) URI의 마지막에 슬래시를 넣지 말 것!
/articles/:id/ (BAD👿)
/articles/:id (GOOD😻)3-2) [ 대문자, 언더바(_) ] 대신 하이픈(-)을 사용하자!
/articles/i_love_soccer (BAD👿)
/articles/i-love-soccer (GOOD😻)짧고 알기 쉬운 URI가 가장 이상적이겠지만, 의미전달을 위해 불가피하게 긴 URI를 사용할 경우, 하이픈(-)을 사용해 가독성을 높이자!
URI는 대소문자를 구별할 줄 알아서, 같은 경로라도 대소문자가 틀리면 다른 경로로 인식하게된다.
언더바(_)의 경우 언더바 자체가 보기 어렵기 때문에 가독성을 위해 사용을 지양한다.
마무리
이제 API를 만들 때 어느정도 기준을 정하고 만들 수 있을 것 같다.
아래 글들을 참고하여 작성된 글입니다 :
https://meetup.toast.com/posts/92
https://spoqa.github.io/2012/02/27/rest-introduction.html
