[WEB] REST API를 알아보자!

REST API

REST(Representational State Transfer)는 월드 와이드 웹과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처의 한 형식이다. (출처 : 위키피디아 REST)

위키피디아에 REST에 대해 위와 같이 설명하고 있다. 로이 필딩이라는 분이 HTTP 프로토콜의 장점을 최대한 활용할 수 있도록 고안한 네트워크 아키텍처이다. 2000년에 처음 소개되었고, 2022년 현재까지 널리 사용되는 API 설계의 원칙이라고 할 수 있다. 

API가 무엇인가요?

웹 상에서 데이터를 주고 받기 위해 HTTP 프로토콜(규약) 을 사용한다. 그리고 HTTP를 사용해서 원활하게 소통하기 위해서 위해서 API라는 것을 만들고 활용한다. API는 간략하게 설명하면, 프로그램끼리 서로 소통할 수 있는 매개체이다.

현실 세계의 예시를 들면, 카페에서 원활이 음료를 주문하고 주문 받기 위해서 '메뉴판'을 활용 하는 것처럼, 웹의 세계 - 클라이언트와 서버간에도 이런 메뉴판 같은 역할을 해줄 매개체가 필요하다. 이를 API라고 할 수 있다. 

REST API가 무엇인가요?

HTTP를 사용해서 소통하는 API를 HTTP API 라고 할 때,
REST 원칙이 잘 적용된 API를 REST API, 혹은 RESTful API 라고 한다.

앞서 HTTP 를 잘 활용하기 위해 고안된 아키텍처 - 방식이라고 했다. API 가 메뉴판이라고 할 때, 보기 좋게 잘 작성된 메뉴판이 주문하기 훨씬 쉬운 것처럼, 잘 정리된 API 가 있으면 그것만 가지고도 HTTP 요청의 내용을 파악하기가 쉬워진다. 

 

그렇다면 REST란 무엇이고, RESTful 한 API 는 어떻게 만드는 것일까? 

 

먼저 단어의 의미를 살펴보자. Representational State Transfer 한국어로 직역하면 대표 상태 전송? 이라는 아리송한 말이 된다. 대표 상태라는게 무엇일까? 일반적으로 HTTP 요청을 통해서 리소스(원본 자원)을 주고 받는다고 말하지만, 정확히는 리소스 원본 자체가 아닌, 서버에 있는 리소스의 현재 상태를 주고 받는 것이다! 이 상태를 JSON 혹은 XML 형식으로 주고받고, 클라이언트에서는 컨텐츠 타입에 맞게 파싱하여 사용할 수 있는 것이다. 아리송한 개념이지만 리소스 자체가 아닌 상태 정보를 주고받는 것이라고 기억하자. REST 는 요청 리소스를 어떻게 명확히 표현하는가에 집중하는 방법론이다.

REST API의 구성

REST API는 자원 resource, 행위 verb, 표현 representations 의 세 가지 요소로 구성된다. 이 세가지 요소는 각각 URI(엔드포인트) / HTTP 요청 메서드 / 페이로드 로 표현된다.

구성 요소	내용	표현 방법
자원 resources	자원	URI (엔드포인트)
행위 verb	자원에 대한 행위	HTTP 요청 메서드(GET, POST 등..)
표현 representation	자원에 대한 행위의 구체적인 내용	페이로드

이 구성요소를 포함하도록 REST API를 설계하는 방법을 레오나르드 리차드슨의 REST 성숙도 모델을 통해서 살펴보도록 하자!

REST 성숙도 모델

0단계 : HTTP 사용

0단계는 단순히 HTTP 프로토콜을 사용하기만 해도 충족된다. 이 단계를 충족했다고 해서 REST API가 되는 것은 아니고, REST API가 되기 위한 기본 단계라고 할 수 있다. 

1단계 : 개별 리소스와의 통신 준수

앞서 설명했듯 REST API에서는 웹에서 사용되는 모든 리소스를 HTTP URI로 표현한다. 즉, URI는 리소스를 표현해야한다! 그리고 모든 자원은 개별 리소스에 맞는 엔드포인트를 사용해야한다. 

API 엔드포인트란 API 호출(요청)이 수행되는 곳이다. 내가 산들이에게 말을 걸 때 '잘 잤어, 산들이?' 라고 한다면, '산들이?' 라는 부분을 통해서 산들이를 호출하는 것이다. 즉 이 안부인사의 엔드포인트는 '산들이'가 될 것이다.

API 서버에 데이터를 요청한다면, 이 데이터는 여기에 있다 => 이렇게 같은 서버 주소에 대해서도 다른 요청, 다른 리소스에 접근할 수 있도록 해주는 URI를 말한다. 

POST /slots/123

위 예시를 보면 이 URI는 slots라는 리소스에서 123이라는 고유 id를 특정지어 표현하고있다. REST API 에서는 이렇게 리소스 간의 계층적인 구조를 / 슬래시를 사용해서 표현하도록 권장한다. 예시에서 알 수 있듯 엔드포인트를 리소스에 집중한 명사 형태로 작성하는 것이 바람직하다. (getSlots 이런 식으로 쓰지 말라는 의미.)

 

추가적으로 요청에 따른 응답으로 리소스를 전달할 때에도, 이 리소스에 대한 정보 및 리소스 사용에 대한 성공/ 실패 여부를 반환해주어야 한다. HTTP 응답 body 안에도 성공 혹은 실패 사유에 대한 표현도 같이 전달해야 한다는 것이다.

 

2단계 : HTTP 메서드 원칙 준수

HTTP 요청 메서드란 클라이언트가 서버에게 요청의 종류와 목적(행위)를 알리는 방법이다. API를 사용하게 되는 경우가 주로 CRUD 에 관련된 것이기 때문에, 이에 해당하는 주요 5가지 메서드를 사용한다. 각 목적에 맞는 정확한 메서드의 사용이 중요하다. 상황에 맞지 않는 메서드를 사용했을 때 예상하지 못한 동작이 일어날 수도 있음에 유의하자.

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

페이로드란 응답 메시지 body를 의미한다. body에 데이터가 실려서 오는지 혹은 오지 않는지 여부를 따지는 것이다. 위 표로 정리된 것 처럼 목적에 맞는 HTTP 메서드를 사용하되, URI는 리소스에만 집중하여 이런 '행위'에 대한 내용을 표현하지 말아야 한다!

HTTP 메서드 사용시 다음과 같은 규칙에 유의하자.
1. GET 메서드는 서버의 데이터를 변화시키지 않는 요청에 사용하자.
2. POST 메서드는 요청마다 새로운 리소스를 생성,
3. PUT 메서드는 요청마다 같은 리소스를 반환한다.매 요청마다 같은 리소스를 반환하는 특징을 ‘멱등’하다 idempotent 라고 표현한다. 따라서 멱등성을 가지는 PUT과 그렇지 않은 POST는 구분해서 사용해야 한다.
4. PUT과 PATCH도 구분해야 한다. PUT은 교체, PATCH는 수정 용도로 사용한다.

로이 필딩은 3단계까지 적용되지 못한 API는 REST API가 아닌 HTTP API 라고 불러야 한다고 주장하지만, 2단계 까지만이라도 잘 적용된 API 디자인도 바람직한 REST API 디자인이라고 볼 수 있다. 

3단계 : HTTP 사용

HATEOAS Hypertext As The Engine Of Application State - 하이퍼 미디어 컨트롤 

 

2단계와 동일하지만, 응답에 리소스의 URI 를 포함한 링크 요소를 삽입해서 작성해야 한다. 이 때 링크 요소에는, 응답을 받은 뒤 할 수 있는 다양한 액션을 위한 많은 하이퍼미디어 컨트롤들을 포함하고 있다.

 

응답 내에 링크를 넣어서, 응답을 받은 후 새 기능에 접근할 수 있도록 하는 것이 3단계의 핵심이다. 

 

참고자료

https://www.cloudflare.com/ko-kr/learning/security/api/what-is-api-endpoint/

https://evan-moon.github.io/2020/04/07/about-restful-api/#%EB%A6%AC%EC%86%8C%EC%8A%A4%EC%9D%98-%EA%B3%84%EC%B8%B5%EC%9D%84-%ED%91%9C%ED%98%84%ED%95%98%EA%B8%B0

프론트엔드와 백엔드가 소통하는 엔드포인트, RESTful API