# REST API - URL

학습 스프린트 기간 동안 프로젝트를 하면서 API를 설계하면서, RESTful, REST API에 대한 키워드를 바탕으로 표면적인 정보만 얻고 느낌으로, 감으로 시도했던 점을 반성한다.

아직 온전한 의미의 REST(REpresentational State Transfer)의 원칙을 설명하기가 어렵다. 특히 ‘자체 표현 구조(self-descriptiveness)’와 ‘HATEOAS(Hypermedia As The Engine Of Application State)’라는 원칙을 API에서 어떻게 적용 가능한지 모르겠다. 아직 전체를 다루기에는 경험치가 부족하다고 판단했다.

학습을 통해서 설명할 수 있게 된 RESTful URL에 대한 부분만을 포스팅에 담아보려고 한다. RESTful의 필수조건 정도로 봐주면 좋겠다. (충분조건이 아니다!)

REST API

REST(REpresentational State Transfer)는 클라이언트가 서버의 리소스에 접근하는 방식을 규정한(제약조건) 아키텍처이며, REST API는 REST를 기반으로 서비스 API를 구현한 것이다.

나는 학습을 통해서 REST API의 장점으로 아래 정도를 말할 수 있게 되었다.

• REST API만으로 HTTP 요청의 내용을 이해할 수 있다.
• server와 client의 독립적 버전업을 가능하게 한다.
• API의 규격화를 통해 사용의 이점을 극대화한다.

(물론 더 많은 장점이 있을 것이고, 설명할 방법도 더욱 많을 것이다.)

URL 설계

URI 설계 원칙

1. 마지막 '/'로 끝나지 않도록
2. 동사 보다는 명사를 사용
3. 단수형 보다는 복수형 명사 사용
4. URI는 기본 소문자 사용
5. 언더스코어( _ ) 대신 하이픈(-) 사용
6. 파일 확장자는 URI에 미포함

API 용도 URL 설계

자원(resource), 행위(verb), 표현(representations) 3개의 요소로 구성된다.

• 자원: 자원(URI 엔드포인트)은 관심의 대상
  • 리소스의 표현(명사)
• 행위: 자원에 대한 행위로 CRUD
  • HTTP 요청 메서드 → get, post, put, patch, delete
• 표현: 자원에 대한 행위의 구체적 내용
  • 페이로드 → body

HTTP 요청 메서드	의미	목적	페이로드
GET	조회	모든/특정 리소스 취득	X
POST	생성	리소스 생성	O
PUT	교체(전체)	리소스의 전체 교체	O
PATCH	수정(일부)	리소스의 일부 수정	O
DELETE	삭제	모든/특정 리소스 삭제	X

• 페이로드: 헤더와 메타데이터와 같은 데이터는 제외한 사용에 있어서 전송되는 데이터

예시

• GET /user?age=20 - 20살 유저를 조회한다.
• POST /user - 유저를 생성하겠다.
• PUT /user:id - 유저 정보를 전면 교체한다.
• PATCH /user:id - 유저 정보를 일부 수정한다.
• DELETE /user/:id - id에 해당하는 유저를 삭제한다.
• GET /room/:key - key에 해당하는 방을 상세 조회한다.
• GET /room?page=1&limit=12 - 특정 방 목록을 조회한다. (12row/1page인 1페이지 조회)
• POST /room - 방을 추가한다.
• PUT /room/:key - key에 정보를 전면 교체한다.
• PATCH /room/:key - key에 정보를 일부 수정한다.
• DELETE /room/:key - key에 해당하는 방을 삭제한다.

추가학습

Q. 클라이언트에서 서버로 데이터를 전달할 방법

• URL Params(Path Variable)
  • URL 계층적으로 의미가 있어 명확한 resource 식별이 가능한 경우
  • 라우팅이 잘못 설정된 경우 404로 연결될 가능성이 있음(고객 경험 측면에서 좋지 않을 수 있다.)
• Query Parameter
  • {URL}?key=value 형태로 세부적인 정보 제공하고 보다 값의 의미를 알기 유리한 부분이 있음
  • 복수의 데이터를 받아야 하는 경우 적합하고, body와 달리 주소만 전달하면 되는 편의성
• Body(payload)
  • 데이터양이 많은 경우 적합(URL의 경우 길이 제한 발생함)
  • URL로 노출하기 부적절한 경우, 부적합한 경우(띄어쓰기 있는 정보 등 인코딩이 강제될 때…)

참고자료

• 이웅모, 모던 자바스크립트 Deep Dive, 위키북스, 2020, pp.830-831
• 김동범, “REST API 제대로 알고 사용하기”, NHN Cloud, 2016.07.25., https://meetup.toast.com/posts/92
• 이응준, “그런 REST API로 괜찮은가”, DEVIEW2017, https://deview.kr/2017/schedule/212
• Jeongsu Han, "[번역] Path Variable과 Query Parameter는 언제 사용해야 할까?”, Integerous DevLog, 2019.04.23., https://ryan-han.com/post/translated/pathvariable_queryparam/
• dar0m!, “[Web] param vs query vs body”, DR-Kim, 2021.04.18., https://dar0m.tistory.com/222
• https://www.moesif.com/blog/technical/api-design/REST-API-Design-Best-Practices-for-Sub-and-Nested-Resources/