[Spring Boot - 🐱PetClinic🐶] 7. REST API 분석🔍

🚀 REST API란?

REST API의 REST는 Representational State Transfer의 약자로 API 작동 방식에 대한 조건을 부과하는 소프트웨어 아키텍처다. REST 아키텍처 스타일의 원칙은 다음과 같다.

• 균일한 인터페이스(Uniform)
  URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행
• 무상태(Stateless)
  작업을 위한 상태정보를 따로 저장하고 관리하지 않음, 단순히 들어오는 요청만을 처리
• 계층화 시스템
  다중 계층으로 구성될 수 있음
• 캐시 가능성(Cacheable)
  HTTP를 사용하기 때문에 HTTP가 가진 캐싱 기능 적용 가능(Last-Modified 태그나 E-Tag 이용)
• 온디멘드 코드
  서버는 프로그래밍 코드를 클라이언트에 전송하여 클라이언트 기능을 일시적으로 확장하거나 사용자 지정할 수 있음
• Server-Client 구조
  서버 측에서는 API 제공, 클라이언트 측에서는 사용자 인증, 컨텍스트(로그인, 세션 정보) 등을 관리하는 구조로 각자의 역할이 분리되기 때문에 각자의 개발 내용이 명확해지고 서로간의 의존성이 낮아짐

REST API를 사용하면 확장성, 유연성, 독립성 있는 통신이 가능해진다.

📋 REST API 디자인

RESTful한 설계를 위해서는 다음의 두 가지를 지켜줘야 한다.

• URI는 정보의 자원을 표현해야 한다.
  • '/'는 계층관계를 나타낼 때 사용한다
  • 마지막 문자로 '/'를 포함하지 않는다.
  • '-'는 가독성을 높이는데 사용하고, '_'를 사용하지 않는다.
  • URI 경로에는 소문자만 사용한다.
  • 파일 확장자는 URI에 포함시키지 않는다. (Accept header 사용)
• 자원에 대한 행위는 HTTP Method(POST, GET, PUT, DELETE)로 표현한다.

Method	Role
POST	리소스 생성(Create)
GET	리소스 요청(Read)
PUT	리소스 수정(Update)
DELETE	리소스 삭제(Delete)

🚥 HTTP 응답 상태 코드

요청에 대한 처리 결과로 서버 측에서 클라이언트 측으로 보내는 응답 상태 코드, 처리 결과에 따라 알맞은 응답 코드를 보낸다.

상태코드	내용
200 🟢	요청을 정상적으로 수행함
201 🟢	리소스 생성 요청을 정상적으로 수행함
301 🟠	URI 변경(Location header에 변경된 URI 적어줘야함.)
400 🔴	부적절한 요청
401 🔴	인증되지 않은 클라이언트의 요청
403 🔴	응답하고 싶지 않은 요청(403보단 400이나 404 사용을 권함)
404 🔴	요청한 리소스를 찾을 수 없음
405 🔴	사용 불가능한 Method 사용
500 🔴	서버에 문제가 있을 경우 사용(Runtime Exception 등)

🐶 Pet Clinic URI 분석

요청 URI는 각 도메인별 Controller에서 찾을 수 있다.

• WelcomeController : index 페이지 요청

Method	URI	설명
GET	/	index 페이지 요청

• OwnerController : onwer 관련 조회/추가 요청

Method	URI	설명
GET	/owners/new	owner 추가 페이지 요청
POST	/owners/new	owner 추가 요청
GET	/owners/find	owner 찾기 페이지 요청
GET	/owners/	owner 리스트 페이지 요청
GET	/owners/{ownerId}/edit	owner 수정 페이지 요청
POST	/owners/{ownerId}/edit	owner 수정 요청
GET	/owners/{ownerId}	owner 상세정보 페이지 요청

• PetController : pet 관련 조회/추가 요청

Method	URI(/owners/{ownerId} + )	설명
GET	/pets/new	pet 추가 페이지 요청
POST	/pets/new	pet 추가 요청
GET	/pets/{petId}/edit	pet 수정 페이지 요청
POST	/pets/{petId}/edit	pet 수정 요청

• VisitController : visit 관련 조회/추가 요청

Method	URI	설명
GET	/owners/{ownerId}/pets/{petId}/visits/new	visit 추가 페이지 요청
POST	/owners/{ownerId}/pets/{petId}/visits/new	visit 추가 요청

• VetController : vet 관련 조회 요청

Method	URI	설명
GET	/vets.html	vet 목록 조회 페이지 요청
GET	/vets	vet 리스트 요청

• CrashController : 오류페이지 요청

Method	URI	설명
GET	/oups	오류 페이지 요청

❓ PUT vs POST

Pet Clinic의 URI 분석을 하다 보니 CRUD를 위해 POST/GET/PUT/DELETE를 사용한다고 했는데 POST와 GET만 사용하고 PUT과 DELETE는 사용하지 않았다. DELETE야 기능 구현상 쓰이지 않아서 없다 치더라도 수정을 위해 PUT을 사용하지 않는다는 점이 이해가 가지 않아 찾아봤다.

PUT은 자원이 존재하지 않을 경우 '생성', 존재할 경우 '수정'하는 방식이고, POST는 자원의 '생성'을 위한 방식이다. PUT과 POST의 가장 큰 차이점은 멱등(idempotent)에 있다고 한다. 멱등성을 수식으로 표현하자면 'f(x) = f(f(x))'다. 몇 번을 반복해도 결과가 같다는 의미다. PUT은 멱등하고 POST는 멱등하지 않다. PUT은 몇 번을 시도해도 결과가 같지만, POST는 시도할 때마다 결과가 다를 수 있다. 똑같은 세 번의 요청을 서버에 전송한다고 할 때, PUT은 서버에 요청에 대한 처리 결과가 없다고 할 때 처음은 생성, 나머지 두 번은 수정 처리를 할 것이다. 반면 POST는 세 번의 요청 모두 생성 처리를 한다는 점에서 차이가 있다.

이것은 이론적인 얘기고, 그래서 왜 'PUT으로 넘겨야 할 것 같은데 POST 방식으로 넘기느냐'에 대해 찾아봤다. 수정을 위한 요청 전송 방식은 PUT, PATCH, POST 세 가지로 볼 수 있는데, PUT은 수정보다는 교체(Replace)에 더 가까운 것 같다. 부분 수정을 위해서는 PATCH와 POST를 사용한다. 그러나 PATCH를 사용하긴 까다롭기 때문에(safe 하지 않고 idempotent 하지도 않은 방식, 실행에 따라 결과가 바뀔 수 있음, E-Tag와 비롯한 여러가지 고려해야함) 주로 자원의 부분 수정을 위해서는 POST를 사용한다는 것이다.

여러 글에서 설명할 때는 POST가 생성을 담당한다고는 했지만 실제로는 생성과 수정에 모두 사용하는 것 같다. (특정한 상황에서만 PUT을 사용하고 보통 우리가 생각하는 일부 수정의 경우는 POST를 쓰는 것이 일반적인 것 같다.) Pet Clinic에서도 전체 수정이 아닌 일부만 수정하기 때문에 PUT이 아닌 POST 방식을 사용하는 것 같다.

🧩 마무리

각 요청 URI에 따라 정해진 일련의 동작을 수행하는 게 서버의 역할이다. 이 요청 URI를 어떻게 구성할 것인지가 Backend의 핵심이지 않을까? 일단 이번 글에서는 서버로 들어올 수 있는 요청의 종류에 대한 내용을 다뤘다. 다음 글에서는 들어온 이 요청들이 어떻게 처리되는지에 대해 컨트롤러별로 다룰 예정이다. REST API에 대한 자세한 내용은 참고 링크를 참고하면 된다.

[참고]

REST API 설명 -
https://aws.amazon.com/ko/what-is/restful-api/
https://meetup.nhncloud.com/posts/92
PUT vs POST -
https://repo.yona.io/doortts/blog/issue/12
https://www.keycdn.com/support/put-vs-post
http://1ambda.github.io/javascripts/rest-api-put-vs-post/