REST API와 성숙도 모델

REST API

REST는 Representational State Transfer의 약자이다.

HTTP를 더 잘 사용하고자 로이 필딩이 그의 박사 논문에서 제안한 것이 기원이다.

웹의 리소스를 HTTP URI 형식으로 표현하고 HTTP를 통해 요청과 응답을 정의하는 방식이 REST API이다.

그러니까 REST API는 특정 API를 말하는 것이 아니라, API의 구축 방식을 말하는 것이라고 보면 된다. 

어떤 API가 REST API의 형식을 갖추고 있으면 RESTful하다고 말한다.

 

REST API 성숙도 모델 (Richardson maturity model)

로이 필딩의 이론을 기반으로 리차드슨이 제안한 모델이다.

0단계부터 3단계까지 있으며 단계가 올라갈수록 성숙도가 높은 API라고 볼 수 있다. 

창시자 로이 필딩은 3단계까지 잘 지켜야 REST API라고 주장했다. (그 전까지는 그냥 HTTP API이다.)

하지만 실제로 3단계까지 지키기는 힘들고, 성숙도 모델의 2단계까지만 지켜도 잘 작성된 API라고 한다.

0단계는 일단 HTTP 프로토콜을 사용하는 것이다. 

 

1단계는 각 개별 리소스에 맞는 엔드포인트를 사용하여 요청하는 것이다.

엔드포인트는 클라이언트가 요청한 정보를 받는 서버의 마지막 지점이다.

API endpoints are the specific digital location where requests for information are sent by one program to retrieve the digital resource that exists there.

Resource-based addressing 리소스 기반으로 주소를 작성하는 것. 

엔드포인트는 의미를 파악할 수 있는 명사 형태로 작성하는 것이 바람직하다. 

 

2단계는 CRUD에 맞게 적절한 메소드를 사용하는 것이다.

각 메소드마다 목적이 다르기에 잘 구별해서 써야 한다. 

GET은 정보를 읽을 때 쓴다.

PUT은 요청마다 같은 리소스를 반환하는 반면 POST는 요청마다 새로운 리소스를 반환한다. 

PUT처럼 매 요청마다 같은 리소스를 반환하는 것을 멱등하다고 한다. 

또, PUT은 교체의 용도로 PATCH는 수정의 용도로 사용한다는 것도 알아두어야 한다. 

 

3단계는 HATEOAS(Hypertext As The Engine Of Application State)를 사용하는 것이다.

Hypertext라고 하는 곳도 있고, Hypermedia라고 하는 곳도 있다.

당장 이 글의 이미지에서도 Hypertext라고 하고 있지만, 위키피디아에 쳐보면 Hypermedia라고 나옴. 

(동기분의 말씀을 보니 Hypermedia가 Hypertext를 포괄하는 개념이라고 한다.)

3단계는 2단계와 다른 점이 딱 하나 있는데 그건 바로 응답 내에 새로운 링크를 넣는 것이다. 

 

Open API와 API Key

Open API는 말 그대로 누구나 접근할 수 있는 API이다.

하지만 그 API를 무제한으로 이용할 수 있는 것은 아니다. 

API마다 각자의 수칙이 있고, 그에 따른 요금 지불이나 접근 범위의 제한이 있을 수 있다.

 정부에서 제공하는 공공데이터도 Open API의 형태로 제공되고 있다. 

 

API를 이용하기 위해서는 API Key가 필요하다.

서버에서 데이터를 받아오려면 운용 비용이 발생하는데 아무 조건도 없이 API의 정보를 제공할 이유가 없기 때문이다. 

(API Key가 없는 API가 있기도 하다.)

데이터를 요청할 때 API Key도 같이 보내면 원하는 정보를 받을 수 있다.

 

 

참고 링크

Richardson Maturity Model

 

What Is an API Endpoint? Definition from SearchAppArchitecture

 

REST API(RESTful API, 레스트풀 API)란 - 서버, 구현, 사용법