REST API, REST 성숙도 모델

REST API?

웹 애플리케이션은 HTTP 메서드를 이용해서 서버와 통신한다. 이러한 HTTP 메서드를 이용해서 데이터를 주고 받을 수 있도록 서버 개발자가 API를 만들텐데 이 때 Restful한 API를 만드는 것이 좋다. 요청과 응답을 제대로 보내고 받을 수 있도록 일종의 규약이 정해져 있다. 

REST API의 REST는 Representational State Transfer의 약자로, 로이 필딩(Roy Fielding)의 박사학위 논문에서 소개된 아키텍처이다. 웹에서 사용되는 데이터나 자원(resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식을 말한다.

 

REST 성숙도 모델 

어떻게 RESTful API를 만들 수 있을까? 레오나르드 리차드슨(Leonard Richardson)이 다음과 같이 4단계 모델을 제안했다. REST API를 만들기 위한 체크리스트와 같다. 이 모든 단계를 충족하면 좋겠지만 실제로 엄밀하게 다 지키기는 어렵기 때문에 통상적으로 2단계까지만 지켜도 RESTful 하다고 할 수 있다. (로이 필딩은 2단계까지만 만족한 API는 HTTP API라고 불러야 한다고 주장한다.)

출처 코드스테이츠 학습자료

 

0단계 HTTP 사용

0단계를 충족하기 위해서는 단순히 HTTP 프로토콜을 사용하기만 해도 된다. 어떤 데이터를 삭제할 때 DELETE가 아닌 POST 메서드를 사용하더라도 바람직하지 않지만 HTTP 프로토콜을 사용한 것이므로 0단계에 해당 된다. (아직 REST API는 아니다)

 

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

개별 리소스와의 통신 준수는 자원에 따라 적합하게 통신을 해야 한다는 것이다. URI로 자원을 알맞게 표현해야 한다. 이는 모든 자원이 각각 자신에게 맞는 엔드포인트를 갖는 것으로써 가능하다. 엔드포인트 작성은 동사, HTTP 메서드, 또는 행위 같은 단어를 지양하고 리소스를 표현할 수 있는 명사로 작성하는 것이 바람직하다.

GET /getTodos/1 // bad, http메서드용어 사용
GET /todos/show/1 // bad, 동사 사용

GET /todos/1 // good

또한 요청한 리소스에 대해 성공적으로 완료할 수 없을 경우, 단순히 실패로 끝나는 것이 아니라 성공/실패 여부를 포함하여 응답을 주어야 한다. 클라이언트가 병원 예약을 하기 위해 예약을 생성하는 POST 요청을 보내왔는데 해당 시간에 이미 예약이 되어있어서 성공적으로 처리하지 못한다면, '해당 시간에는 이미 예약이 되어 있습니다'와 같은 실패 사유와 함께 실패했다는 응답을 주어야 바람직하다.

 

2단계 HTTP 메소드 원칙 준수

HTTP 요청 메서드는 클라이언트가 서버에게 하는 요청의 종류와 목적을 나타낸다. GET, POST, PUT, PATCH, DELETE 를 사용하여 CRUD를 구현한다. 하고자 하는 작업에 대해서 합리적인 행위 메서드를 사용해야 한다. 0단계에서 든 예시로 어떤 데이터를 삭제할 때 DELETE를 사용하지 않고 POST를 사용했다면 2단계를 충족하지 못한다. 

응답에서 주는 상태코드 또한 규칙이 있다. 예약을 생성(Create)하는 POST 요청에 대한 응답이라면 단순히 코드 200으로 성공을 나타내는 것이 아닌 예약이 잘 생성되었다는 201 Created로 주는 것이 더욱 RESTful하다.

 

3단계 HATEOAS 원칙 준수

내용 추가 예정

 

Open API와 API Key

Open 이라는 단어가 붙은 API는 공공데이터처럼 API를 무료로 사용할 수 있다. 하지만 Open API도 자신들의 서버를 운영하며 제공하는 것이기 때문에 언제나 무제한으로 이용 가능한 것은 아니다. API별로 하루에 사용할 수 있는 횟수나 고급 기능을 위한 유료 이용 등 이용 수칙이 정해져 있다. API를 이용하기 전에 이용 수칙을 잘 확인해보아야 한다.

API를 이용하기 위해서는 API Key가 필요하다. 열쇠같은 것이다. 아무런 조건 없이 익명의 사용자에게까지 서비스를 제공할 의무는 없기 때문에 API 사용자를 식별하기 위해 요구하곤 한다. 요청을 할 때 API Key를 같이 전달해야 원하는 응답을 받을 수 있다. API를 제공하는 서비스에서 설명서에 API Key 발급 방법과 요청 방법 등을 작성해 놓았을 것이다.