REST란?
등장 배경
만들어질 당시 웹이 HTTP를 제대로 사용하지 못하고 있어, HTTP의 장점을 최대한 활용하고 프로토콜을 의도에 맞게 디자인하고자 소개되었다.
그래서 REST는
REpresentational State Transfer
REST는 HTTP를 기반으로 클라이언트가 서버의 리소스에 접근하는 방식을 규정한 아키텍처다.
쉽게 말해서, 서버의 데이터에 접근하는 방식이다.
REST API
REST API는 REST를 기반으로 서비스 API를 구현한 것을 말한다.
웹에서 사용되는 리소스를 HTTP URI로 표현하고, 요청과 응답은 HTTP 프로토콜을 통해 정의한다.
구성 요소
REST API는 다음 3가지 요소로 구성된다.
자원: 자원 자체행위: 자원에 대한 행위 (CRUD)표현: 자원에 대한 행위의 구체적 내용
자원에 대한 행위와 그 표현이 API에 잘 나타나있어야, 부가적인 설명 없이 API 자체만으로도 설명 가능해야 한다는 제약 조건(self-descriptiveness)을 만족할 수 있다.
REST API 설계하기
클라이언트가 서버의 리소스를 활용하려면 서버는 클라이언트에게 모두가 잘 알아볼 수 있는 API를 제공해야 한다. 이 API를 REST를 기반으로 구현하기 위해 지켜야할 중심 규칙이 있다.
가장 중요한 기본적인 원칙 두 가지는 다음과 같다.
-
URI는 리소스를 표현하는데 집중해야 한다.
URI는 리소스를 표현하는 것이지 행위에 대한 표현이 들어가면 안 된다. 떄문에 동사를 제외하고 명사 위주로 사용해야 한다.
GET /getTodos/1 // X : 행위에 대한 표현(get)이 있으면 안 된다. GET /todos/1 // O -
행위에 대한 정의는 HTTP 요청 메서드로 해야 한다.
리소스를 취득하려면 GET, 삭제하려면 DELETE를 사용해 리소스에 대한 행위는 HTTP 메서드로 명확하게 표현해야 한다.
GET /todos/delete/1 // X : URI에 행위에 대한 표현(delete)이 있으면 안 되며, '삭제' 행위는 HTTP 메서드로 표현해야 한다. DELETE todos/1 // O
[참고] HTTP 요청 메서드
주어진 리소스에 수행하길 원하는 행동을 나타내는 메서드다.
HTTP 요청 메서드 목적 GET 특정 리소스의 표시 요청한다. 오직 데이터를 받기만 한다. POST 특정 리소스에 엔티티(페이로드)를 제출한다. PUT 목적 리소스의 현재 표시를 요청한 내용(페이로드)으로 교체한다. DELETE 특정 리소스를 삭제한다. PATCH 리소스의 일부분을 (페이로드 내용으로) 수정한다.
이렇게 원칙을 지켜 작성한 API를 RESTful API라고 한다.
REST 성숙도 모델
RMM: REST Maturity Model
로이 필딩이 제시한 REST 방법론을 실용적으로 적용하기 위해 레오나르드 리차드슨은 REST API를 잘 적용하기 위한 REST 성숙도 모델을 만들었다.
RMM은 네 단계로 이루어져 있으며, 모든 단계를 엄밀히 충족하기엔 어려움이 있어 세 단계(0~2)까지만 적용해도 좋은 API 디자인으로 볼 수 있다고 한다.
0단계: HTTP 사용
HTTP 프로토콜을 사용해야 한다. 이는 REST API를 작성하기 위한 기본 바탕이 된다.
즉, 0단계에서는 하나의 엔드포인트를 사용하기 때문에 매개변수를 통해 여러 동작을 한다. 따라서 HTTP 메서드는 페이로드(매개변수를 전달하기 위함)가 있는 POST만을 사용한다.
[0단계] HTTP 프로토콜을 사용하며, POST 메서드로 하나의 엔드포인트에만 접근한다.
1단계: 개별 리소스와의 통신 준수
REST API는 웹에서 사용되는 모든 리소스들을 HTTP URI로 표현해야 한다. 따라서 모든 리소스는 개별 리소스에 맞는 엔드포인트(URI)를 사용해야 하고, 요청하고 받는 리소스에 대한 정보를 성공/실패 여부를 포함해 응답으로 전달해야 한다.
즉, 1단계에서는 모든 요청을 하나의 엔드포인트로 보내는 것이 아니라 각 리소스의 개별적인 URI를 사용해 통신한다. 이때 GET, POST 메서드만 사용한다.
[0단계]
특정 문서(개별 리소스)를 참조하고 싶다면, 전체 문서에 해당하는 엔드포인트를 통해 접근
- /articles
[1단계]
특정 문서(개별 리소스)를 참조하고 싶다면, 특정 문서에 해당하는 엔드포인트(개별 URI)를 통해 접근
- /article/1
- /article/2어떤 리소스를 변화시키고, 어떤 응답이 제공되는지에 따라 상이한 엔드포인트를 사용하기 때문에 적절한 엔드포인트를 사용해야 한다.
[1단계] POST, GET 메서드로 개별 리소스의 엔드포인트에 접근하며, 응답에는 요청에 대한 성공/실패 여부가 포함되어 있다.
2단계: HTTP 메서드 원칙 준수
1단계까지는 POST와 GET 메서드만을 사용해 API를 구현했다. 2단계부터는 요청의 목적(CRUD)에 맞는 HTTP 메서드를 사용해야 하며, 응답에는 단순한 성공/실패 여부가 아닌 명확한 상태 코드를 포함해 전달해야 한다.
[2단계] HTTP 메서드를 사용해 CRUD를 나타내야 하며, 응답 메시지에는 status code를 포함시켜야 한다.
3단계: HATEOAS 원칙 준수
마지막 단계에서는 하이퍼미디어 컨트롤을 적용한다. 요청은 2단계와 동일하며 응답에 리소스의 URI를 포함한 링크 요소를 삽입해야 한다는 점이 다르다. 어떤 요청의 다음 요청에 필요할 만한 엔드포인트까지 링크로 제공한다. 즉, 클라이언트에게 이 요청 다음에는 무엇이 가능할지에 대한 힌트를 URI로써 제공하는 역할이다.
[3단계] 리소스의 URI를 링크로 포함시킨 응답을 제공해야 한다.
[참고] Open API
누구에게나 열려있는 API를 말한다. 정해진 수칙을 따르면 해당 API를 사용할 수 있다.
이런 Open API는 보통 API Key를 필요로 한다. API 사용을 위해 키를 발급 받고, 데이터를 요청할 때 발급 받은 API Key를 함께 전달해야 API를 통해 원하는 정보를 가져올 수 있게 된다.
