최근 만들어보고 싶은 어플리케이션이 생겨서 기획중에 있다. 현재 나는 모바일 개발자로서 취업준비를 하고 있지만, 서버에 대한 궁금증도 항상 있었기에 이번 프로젝트에서는 한번 백엔드와 프론트엔드를 모두 만들어보려고 하고 있다.
이 때 API를 설계할 때 REST 아키텍처를 따를 예정이고, 이때 참고할 만한 자료를 직접 만들면서 제대로 이해하기 위해 이 포스팅을 작성하게 되었다.
서론이 너무 길어졌다😇 얼른 API를 REST하게 만들어보자✏️

앗 그 전에 REST에 대해 잘 모른다면 [API] REST에 대해 알아보자를 읽고 오면 더 이해가 쉬울 것이다😊

📌 Richardson Maturity Model(RMM)

Richardson Maturity Model은 웹 API에 대한 성숙도 모델이다. RMM은 RESTful 웹 API가 얼마나 잘 디자인 되었는지 평가하는 데 유용한 지표가 될 수 있다.
이 모델은 4 Level(0~3)로 분류되어있으며, 단계가 높을수록 REST 아키텍쳐 스타일을 더 따른다고 볼 수 있다고 한다. 그리고 다음 단계에는 이전 단계의 모든 특성이 포함된다.

Level 0: The Swamp of POX

단일 URI(endpoint)와 단일 HTTP Method(주로 POST)로 여러가지 작업을 다 처리하게끔 설계
(HTTP Request body에 어떤 요청인지에 대한 정보를 담아 어떤 요청인지 구분한다.)

예시)

URI	HTTP Method	처리 작업
/cafeService	POST	모든 직원 검색, 메뉴 추가/삭제, 예약 추가/삭제 등

• Level 0으로 설계된 시스템은 RESTful로 분류되지 않는다.

Level 1 : Resources

리소스 개념이 도입되고, 리소스마다 개별 URI에 요청을 보낼 수 있게끔 설계
하지만 여전히 단일 HTTP Method(주로 POST)를 사용

예시)

URI	HTTP Method	처리 작업
/staffs	POST	직원 검색, 직원 추가/삭제 등
/menus	POST	메뉴 검색, 메뉴 추가/삭제 등
/reservations	POST	모든 예약 검색, 예약 추가/취소 등

• Level 1 정도로 설계된 시스템도 RESTful로 보지 않는다.

Level 2 : HTTP Verbs

HTTP Method를 적절히 사용하여 자원을 어떻게 처리할 것인지 구분할 수 있도록 설계
또한 요청 처리 상태에 따라 HTTP Status Code도 적절하게 반환

예시)

URI	HTTP Method	처리 작업
/staffs	GET	직원 검색
/staffs	POST	직원 추가
/staffs	DELETE	직원 삭제
/menus	GET	메뉴 검색
/menus	DELETE	메뉴 삭제
/reservations	GET	예약 검색
/reservations	DELETE	예약 취소

Level 3: Hypermedia Controls

Hypermedia를 통해 리소스를 제어할 수 있도록 설계 / Level2에 HATEOAS가 추가된 레벨
Hypermedia란 다양한 미디어(텍스트, 이미지, 영상 등)를 하이퍼링크로 연결해 구성한 것이다.
HATEOAS (Hypermedia As The Engine of Application State)란 서버가 클라이언트에게 Hypermedia를 통해 정보를 동적으로 제공해주는 것이다.
이를 통해 이번 요청 다음 단계에 할 수 있는 행동에 무엇이 있는지, 그때 필요한 리소스의 URI는 무엇인지 한꺼번에 알려준다.

• 장점 : 클라이언트에서 다음 단계 행동에 대해 판단할 필요 없이, 서버의 응답으로 다음 작업을 정의할 수 있다.

예시 )
staffs를 새로 추가하면, 다음에는 모든 staff의 목록을 불러올 수 있다.

• 요청 : POST /staffs
• 응답

{
	"id": 1003,
  	"name": "Sunny".
  	"_links": {
  		"all-users": {
  			"href": "http://localhost:8080/users"
		}
	}
}

• Level 3까지 지켜진 API가 REST하게 짜기 위한 기본 조건이라고 한다.

📌 REST하게 URI 디자인을 위한 규칙

규칙1: URI에 마지막 슬래시(/)를 포함해서는 안 된다.

마지막에 추가된 슬래시(/)가 혼란을 일으킬 수 있기 때문에 이를 막기 위해 따라야할 중요한 규칙 중 하나이다.

http://localhost:8080/users/ (X)
http://localhost:8080/users  (O)

규칙2: 슬래시(/)로 계층적 관계를 나타낸다.

슬래시(/)를 통해 리소스들 간의 관계를 표현할 수 있다.

ex) id가 1003인 user의 모든 post를 가져오기

http://localhost:8080/users/1003/posts

규칙 3: URI의 가독성을 높이기 위해 하이픈(-)을 사용해야 한다.

URI를 작성할 때 영어에서 공백이나 하이픈을 사용하는 모든 곳에 하이픈(-)을 사용해야 한다.
이는 가독성을 높여 사람들이 URI를 쉽게 스캔하고 해석할 수 있게 해준다.

ex) Computer Science와 관련된 모든 post를 가져오기

http://localhost:8080/posts/computer-science

규칙 4: URI에는 밑줄(_)을 사용하면 안 된다.

텍스트 뷰어 애플리케이션(브라우저, 편집기 등)은 종종 URI에 밑줄을 긋고 클릭할 수 있다는 시각적 신호를 제공한다. 그로 인해 밑줄(_)문자가 가려질 수 있어 사용자에게 혼란을 가져다줄 수 있다.
따라서 밑줄(_) 대신 하이픈(-)을 사용해야 한다. (규칙 3)

ex) Computer Science와 관련된 모든 post를 가져오기

http://localhost:8080/posts/computer_science (X)
http://localhost:8080/posts/computer-science (O)

규칙 5: URI path에는 소문자를 사용하는 것이 좋다.

URI path에서는 소문자를 선호한다.
RFC 3986은 scheme(http, https, ftp 등)과 host components(ex. velog.io, www.google.com)은 제외하고 URI를 대소문자 구분으로 정의한다.

예시2)

https://velog.io/@ddanglehee/Posts (X)
https://velog.io/@ddanglehee/posts  (O)

예시2) 다음 두 URL은 동일하다고 간주한다. (브라우저에 검색하면 똑같은 결과가 나온다.)

https://velog.io/@ddanglehee/posts (O)
https://VELOG.IO/@ddanglehee/posts (O)

규칙 6: 파일 확장자는 URI에 포함되어서는 안 된다.

URI에 파일 확장자를 포함하지 않고, 헤더의 Content-Type으로 미디어의 유형 정보를 통해 콘텐츠를 처리하도록 해야한다.

https://localhost:8080/posts/computer-science/rest.json  (X)
https://localhost:8080/posts/computer-science/rest       (O)

규칙 7: Endpoint 이름은 복수로 작성한다.

만약 특정한 리소스를 지칭하고 싶으면 Depth로 구분하면 된다.

https://velog.io/@ddanglehee/post (X)
https://velog.io/@ddanglehee/posts (O)

https://velog.io/@ddanglehee/posts/restful-api

규칙 8: 리소스 표현은 동사 형태보다는 명사 형태를 사용한다.

리소스는 명사 형태로 표현하고, 동사 표현은 HTTP Method로 구분하면 된다.

     https://localhost:8080/create-user (x)
POST https://localhost:8080/users       (O)

💬 여담
결국 REST하게 API를 설계하려는 목적에는 해당 API를 소비하는 사람들이 간단하고 직관적으로 이해할 수 있도록 하는 것도 포함되어 있다는 걸 느낀다.
RESTful API를 설계하는데 HTTP를 뺴놓을 수 없으니 조만간 HTTP도 공부해야겠다☺️

🌐 참고 사이트
https://martinfowler.com/articles/richardsonMaturityModel.html
https://blog.restcase.com/7-rules-for-rest-api-uri-design/