안녕하세요. 오늘은 REST API에 대해 알아보려 합니다.

REST API의 역사

REST API의 REST는 Representational State Transfer로 직역하자면 상태를 표현한 내용을 전달하는 것입니다. 처음 고안한 사람은 Roy Fielding으로 박사학위 논문 Architectural Styles and
the Design of Network-based Software Architectures에서 이를 소개하고 있습니다.

해당 논문의 챕터5 REST 부분을 보시면 통신에 있어 상세 구현이나 프로토콜적인 부분은 추상화하고, 통신할 때 필요한 자료와 자원에 집중하여 인터페이스를 설계하자는 개념입니다. 흔히 쓰는 RESTful의 의미는 REST의 개념을 잘 이해하고 적용한 좋은 설계의 API들을 RESTful하다고 표현합니다.

보다 RESTful한 API를 설계하기 위해 Conceptual했던 초기안을 기반으로 Leonard Richardson이라는 사람이 2008년 RMM(Richardson Maturity Model)을 제안합니다. REST 성숙도 모델이라고도 부르는 이 모델은 총 4단계로 이뤄지며 모델에서 요구하는 사항을 충족하는 것으로 예전보다 손쉽게 RESTful한 설계가 가능해졌습니다.

REST API란?

그러면 REST API의 탄생 배경을 알아봤으니 어떤 형태의 통신을 REST API라고 하는지 직접 알아봅시다.
이에 앞서 HTTP에 대한 사전지식이 필요합니다. HTTP 글에서 클라이언트 요청을 인용하자면 아래와 같이 표현할 수 있습니다.

GET /restapi/v1.0 HTTP/1.1
Accept: application/json
Authorization: Bearer UExBMDFUMDRQV1MwMnzpdvtYYNWMSJ7CL8h0zM6q6a9ntw

이렇게 서버에서 요청을 받기 위한 주소와 방식을 제공하고 올바른 요청이 들어왔을 때 그에 대한 응답을 주는 것이 HTTP에서의 흔한 API 예라고 볼 수 있는데, RMM에서 제안한대로 올바른 메서드와 데이터 표현 방식을 가지 통신한다면 REST API입니다.

RMM의 단계

0단계

단순히 HTTP 프로토콜을 사용하기만 하는 단계로 목적에 알맞지 않은 메서드를 사용해서 요청하거나, 그에 대한 응답을 하는 API들이 해당하는 단계입니다. 0단계에 해당하는 API들은 REST API라고 볼 수 없습니다.
RESTful한 메서드들은 CRUD로 나눌 수 있는데 각각은 Create(생성), Read(조회), Update(갱신), Delete(삭제)를 의미합니다.
REST API의 개념이 널리 퍼져있지 않던 2000년대 초반에는 0단계에 해당하는 API들이 많았으며 조회를 하는데 POST 메서드를 사용하는 등에 관습이 있었는데요. 이때문에 요청과 응답을 직관적으로 이해하기 쉽지 않았습니다.

예를 들어 POST /users라는 요청을 보냈는데 0번째 사용자 정보를 반환하는 API가 있다면 아래 정보를 얻기 위해서는 어떤 API를 사용해야 하는지 직관적으로 이해하기 어렵습니다.
1. 모든 사용자의 정보를 조회하고 싶을 때
2. 사용자를 생성하고 싶을 때
3. 1, 2, ..., n번 사용자 정보를 조회하고 싶을 때

1단계

1단계에서는 클라이언트가 요청할 때 특정 리소스를 확실하게 지정합니다.
위 예에서 /users/에 해당했던 부분을 endpoint라고 부르는데요. 모든 자원은 자신을 가리키는 endpoint를 가지게 하자는 개념입니다.
이렇게 하면 0단계에서 발생한 문제 3가지 중 1, 3번을 손쉽게 해결할 수 있습니다.

1. 모든 사용자의 정보를 조회하고 싶을 때
   POST /users로 요청 시 모든 사용자 정보를 반환합니다.
2. 특정 사용자 정보를 조회하고 싶을 때
   POST /users/1, POST /users/2와 같은 형태로 사용자에 해당하는 id나 몇 번째 사용자를 호출할지를 지정할 수 있습니다.

2단계

1단계에서도 여전히 POST로만 활용한다면 사용자 정보를 생성, 갱신, 삭제할 때는 별도의 이름으로 endpoint를 만들어야 하는데요. 이는 API의 명료성을 저하시킵니다.
그렇기 때문에 HTTP의 각 목적에 맞는 메서드를 사용하여 API를 요청하게 한다면 보다 RESTful한 설계가 가능합니다.

POST (CRUD - Create)

자원을 생성할 때 사용하는 메서드입니다.POST /users/1로 요청하며 적절한 사용자 정보를 body에 담아 요청하면 사용자가 생성되어야 합니다. 2단계를 충족하기 위해서는 응답코드도 요청 방식에 따라 달라져야 하며 자세한 내용은 HTTP를 참고해주세요.

생성 요청 기준으로 성공 시 201 Created가 반환됩니다.

GET (CRUD - Read)

자원을 요청할 때 사용하는 메서드입니다. GET /users/1로 요청하면 id: 1의 사용자 또는 사용자 배열 중 1번째 사용자를 반환합니다. 이는 서버의 구현에 따라 달라질 수 있으며 id가 되는 것이 조금 더 의미가 분명한 디자인이라 볼 수 있습니다.

성공 시 서버는 200 OK 코드를 반환합니다.
또한 GET 요청으로는 서버의 데이터를 변화시킬 수 없어야 합니다.

PUT, PATCH (CRUD - Update)

자원을 갱신할 때 사용하는 메서드입니다. PUT은 데이터를 완전히 교체, PATCH는 데이터의 특정 부분만을 수정할 때 사용합니다.

멱등성(매 요청마다 같은 리소스를 반환하는 특성)을 가지는 메서드인지 잘 구분해서 사용해야 하는데요. POST는 멱등성을 가지지 않는 메서드입니다.

DELETE (CRUD - Delete)

자원을 삭제할 때 사용하는 메서드입니다. 요청 시 자원이 삭제되어야 합니다.

3단계

요청은 2단계와 동일하게 요청하지만 서버는 HATEOAS(Hypermedia As The Engine Of Application State)라고 부르는 하이퍼미디어 컨트롤을 적용하여 응답합니다.

말이 어려울 수 있는데요. 쉽게 말하자면 요청이 들어왔을 때 서버가 응답하는 본문에 관련된 API들의 링크를 달아주는 형태입니다. 사용자 생성 요청이 들어왔는데 이미 해당 id로 사용자가 있다면 응답에 해당 사용자를 조회할 때 필요한 endpoint 주소와 어떤 메서드를 사용해야 하는지를 함께 반환하는 식의 응답 형태를 말합니다.

Open API

누구에게나 접근이 허용된 API를 말합니다.
이는 무제한적으로 사용이 가능하다는 의미는 아니며, 사전에 접근을 승인받거나(API Key를 신청하는 등) 요청 횟수 등에 제한이 있을 수 있습니다.

우리가 주변에서 흔히 접할 수 있는 Open API에는 정부가 공공 데이터 포털을 통해 제공하는 API가 있습니다.