REST API의 개념과 설계 방법

REST는 Representational State Transfer의 약자로 HTTP 프로토콜을 이용하며 별도의 Transport 전송 계층 없이 간편하게 데이터를 주고 받을 수 있는 인터페이스 규약입니다.

HTTP 프로토콜의 간결한 기능들과 범용적으로 사용되고 있는 현 상황 덕분에 굉장히 자연스럽게 패러다임으로 자리잡았습니다.

그렇다보니 많은 서비스에서 REST를 활용한 REST API를 사용하고, 이러한 REST 환경에서의 아키텍쳐 설계를 RESTful이라고 부르며 이젠 없어서는 안될 존재가 되었습니다.

 

REST API의 구성요소는 다음과 같습니다.

- 리소스(Resource) : 리소스는 HTTP URI로 표현을 합니다.

- 행위(Verb) 리소스에 대한 행위는 HTTP 메소드로 표현합니다.

- 표현(Representation) : 리소스에 대한 행위 내용은 HTTP 메시지 내용으로 표현합니다.

 

또한 REST API는 설계시 기본 규칙이 있습니다.

- 리소스 이름은 가능하면 동사보다 명사를 사용합니다.

- 리소스는 계층적 구조를 가질 수 있으므로 복수형태를 사용합니다.

- GET, POST, PUT, DELETE를 기본으로 사용하되 때에 따라 PATCH도 사용할 수 있습니다.

 

REST API를 설계함에 있어서 우리는 몇 가지 특성을 고려해야 하여 개발해야 견고한 서비스를 만들 수 있습니다.

 

📌 무상태성(Stateless)

REST API는 앞서 설명드린데로 HTTP 프로토콜을 사용합니다. 그렇기에 HTTP의 무상태성의 특성을 그대로 이어받게 됩니다. 무상태성 뿐만 아니라 Cacheable 속성도 함께 물려받지요.

클라이언트는 서버와 커넥션을 맺어 요청을 하고, 응답을 받고 커넥션을 끊는 특징이 있습니다.

이를 활용해 웹서비스는 고가용성을 구축합니다.

진행에 대한 상태를 따로 저장하는 것이 아니기 때문에 로드밸런서를 통해 서버군에 트래픽을 분산하여 전달할 수 있게 됩니다.

무상태성 덕분에 서비스 도중 매우 쉽게 서비스를 증설 또는 축소할 수 있게 되었으며, 배포 또한 매우 쉬워졌습니다.

그렇기 때문에 호출된 API는 하나의 기능을 완전하게 실행해야 합니다.

즉, 여러번의 다른 API호출로 데이터를 조합하여 결과를 만들어내는 방식으로 구현해선 안됩니다.

 

📌 일관성

API를 설계할 때는 같은 형태의 응답 메시지나 일관된 규칙으로 만들어진 HTTP 상태 코드를 정의하여 사용해야 합니다.

일관성은 REST API 뿐만 아니라 클래스나 메소드를 개발할 때도 필요하며 정해진 규칙과 반복되는 패턴으로 일관성이 결정됩니다.

만약 일관성이 결여된 REST API를 개발한다면 예측불가능하고 사용하기도 어려워지며, 매번 기능 개발 시 해당 API가 무슨 책임을 가지는지를 매번 찾아보고 개발해야 합니다.

 

📌 멱등성(Idempotent)

멱등성은 수학용어로 REST API를 설계 및 개발할 때 주의해야 하는 특성입니다.

사전적 의미는 함수를 여러번 적용한 결과와 한 번만 적용한 결과가 같아야 함을 의미합니다.

즉, 클라이언트가 서버로 동일한 API를 여러번 호출해도 결과가 한 번만 요청한 결과와 같아야 하며 이는 API의 멱등성이 존재한다고 표현할 수 있습니다.

일반적으로 GET은 멱등성을 지켜야 하는 메소드로 GET을 통해 데이터가 변경이 된다면 REST API의 기본을 지키지 않은 설계입니다.

데이터를 변경하는 POST 메소드 이외에는 멱등성을 고려해야 하며, PUT이나 DELETE의 경우에도 멱등성을 고려해야 합니다.

 

PUT은 데이터를 수정하는 내용인데 어떻게 멱등성을 유지할 수 있을까요?

이럴 경우 Market의 상태에 따라 isOpened의 값이 변경되게 됩니다.

만약 A와 B가 MarketService의 updateMarketStatus에 접근하여 false인 isOpensed를 true로 변경하려 했다고 해보죠.

그럼 A의 경우 isOpened가 false에서 true로 정상적으로 변경될 것입니다.

하지만 B의 경우 isOpened의 상태가 이미 true로 변경된 상태이다보니 false로 변경되겠지요.

문을 열자마자 닫아버리는 꼴이 됩니다.

 

이를 해결하기 위해선 isOpened를 데이터 기반으로 추론하는 것이 아니라 외부 API호출 시 값을 받아오도록 수정해야 합니다. 이렇게 되면 받아온 값으로 Update를 실행하도록 Repository의 변경도 필요하게 됩니다.

 

✅ 마치며

위의 규칙들을 공통적으로 적용하여 REST API의 일관된 설계를 구축할 수 있습니다.

견고한 서비스를 만드는 그날까지..!!