💡 REST API
웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식
우리가 어떤 식당이나 카페의 손님이고, 식사 혹은 음료를 주문한다고 가정해 보자. 메뉴판의 상태가 아래 사진과 같다면 어떨까? 알아보기도 어렵고, 주문하기도 어려울 것이다.
클라이언트와 서버 사이에도 데이터와 리소스를 요청하고, 요청에 따른 응답을 전달하기 위한 메뉴판이 필요하다. 메뉴판을 보고 손님이 식당에서 음식을 주문하듯 클라이언트는 API를 통해 서버에 요청하고 이에 대한 응답을 받는다.
따라서 HTTP 프로토콜을 기반으로 요청과 응답에 따라 리소스를 주고받기 위해서는 알아보기 쉽고 잘 작성된 메뉴판이 필요한데, 이 역할을 API가 수행해야 하므로 모두가 잘 알아볼 수 있도록 작성하는 것이 중요하다.
그래서 우리는 REST와 같은 가이드라인을 사용한다. REST는 지난 2000년, 로이 필딩(Roy Fielding)이 자신의 박사학위 논문에서 소개한 API 아키텍처 가이드라인이며, 무려 20년이 지난 현재까지도 널리 사용되고 있다.
REST API란?
REST는 REpresentational State Transfer의 약자이다. 직역하면 대표적인 상태 정도의 뜻을 가진 단어이며, 표현된 상태라고 할 수 있다. 이때 이야기하는 상태라 함은 서버가 가지고 있는 리소스의 상태를 이야기한다.
즉, REST는 통신을 통해 자원의 표현된 상태를 주고받는 것에 대한 아키텍처 가이드라인이라고 할 수 있다.
여기서 표현된 상태라고 하는 이유는 리소스 자체를 주고받는 것이 아니라 데이터 리소스를 JSON 등의 방식으로 표현해서 주고받기 때문이다.
REST API의 규칙
- 어떤 자원(리소스)인지 표현 - URI
- 어떤 행위인지 표현 - HTTP Method
URI로 자원을 표현하는 데에 집중하고, 자원의 상태(행위)에 대한 정의는 HTTP METHOD로 하는 것이 REST API를 설계하는 중심 규칙이다.
URI로 어떤 자원(리소스)인지 표현
URI는 이 API가 어떤 리소스에 대한 API인지를 나타내는 요소이다.
예를 들어, 한 유저의 프로필 사진을 가져오는 API가 있다고 생각해보자. 이 API를 사용하는 클라이언트가 접근하고자 하는 리소스는 유저가 될 것이고, 이 API의 URI는 명확하게 유저와 얻고자 하는 자료를 표현하고 있어야 한다.
GET /users/2/profile-image이 URI가 표현하고 있는 리소스인 2번 유저는 유저라는 리소스의 하위 집합이라고 할 수 있고, RESTful API는 이러한 리소스 간의 계층 구조를 /를 사용하여 표현할 것을 권장하고 있다.
URI에서 행위 표현하지 않기
URI를 설계할 때 또 한 가지 중요한 것은 URI에 어떠한 행위를 표현하는 단어는 포함되어서는 안 된다는 것이다.
POST /users/2/delete이 엔드포인트의 URI에는 삭제 행위를 의미하는 delete라는 표현이 포함되어 있다.
이러한 요청은 RESTful API의 가이드라인을 지키며 개발된 다른 애플리케이션들과 통신할 때 어떤 부작용을 발생시킬지 모르기 때문에 위험하다.
위의 엔드포인트를 RESTful 하게 고치면 다음과 같다.
DELETE /users/2행위 표현은 URI가 아니라 HTTP Method에서 사용해야 한다.
HTTP 메서드로 어떤 행위인지 표현
API를 사용하여 하게되는 행위는 대부분 CRUD(Create, Read, Update, Delete)에 속한다.
각 Method 의미
| GET | 리소스를 조회한다 |
| PUT | 리소스를 대체한다 |
| DELETE | 리소스를 삭제한다 |
| POST | 리소스를 생성한다 |
| PATCH | 리소스의 일부를 수정한다 |
이 외에도 HEAD, OPTION, TRACE 등의 메서드도 존재하지만 표에 있는 5개만 확실히 알고 있으면 HTTP 메서드를 사용하여 올바른 행위를 표현하거나 RESTful API를 설계하기에는 전혀 무리가 없다.
PUT과 PATCH의 차이
PUT과 PATCH 메서드는 비슷하게 해석되는 경우가 많기 때문에 차이점을 잘 알아야 한다.
PUT메서드가 의미하는 것은 리소스를 수정하는 것이 아니라 리소스를 요청 바디에 담긴 것으로 대체하는 것이다.
PATCH 메서드는 현재 저장되어 있는 리소스에 수정을 가하는 행위를 의미하기 때문에 굳이 수정하지 않을 사항을 요청 바디에 담아줄 필요도 없다.
멱등성을 가지는 메서드
멱등성이란, 수학이나 전산학에서 어떤 대상에 같은 연산을 여러 번 적용해도 결과가 달라지지 않는 성질을 이야기한다. HTTP 메서드에만 국한된 이야기는 아니고 이는 데이터베이스나 파일에 자원을 읽고 쓰는 등 컴퓨터가 수행하는 모든 연산에 해당되는 이야기이다.
가장 대표적으로 멱등성이 보장되는 연산은 바로 어떠한 수에 1을 곱하는 연산이다. x => x * 1과 같은 함수는 어떠한 값에 1번을 적용하든, 10,000번을 적용하든 항상 x를 반환한다.
그러나 1을 곱하는 것이 아니라 1을 더하거나 빼는 함수라면 한번 호출될 때마다 인자로 주어진 값을 계속 증가시키거나 감소시킬 것이므로 항상 같은 값을 반환하지 않는다. 이러한 성질의 연산이 바로 멱등성을 보장하지 않는 연산의 대표적인 예이다.
POST 메서드는 요청마다 새로운 리소스를 생성하고 PUT 메서드는 요청마다 같은 리소스를 반환한다. 이렇게 매 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 한다. 그렇기 때문에 멱등성을 가지는 메서드 PUT과 그렇지 않은 메서드 POST는 구분하여 사용해야 한다.
Method 멱등성 보장
| GET | O |
| PUT | O |
| DELETE | O |
| POST | X |
| PATCH | X |
HTTP 메서드의 멱등성에 대한 지식은 에러에 대한 정보가 별로 없는 상태에서 디버깅을 진행할 때도 활용될 수 있기 때문에 알고 있는 편이 좋다고 한다.
REST 성숙도 모델
로이 필딩이 논문에서 제시한 REST 방법론을 보다 더 실용적으로 적용하기 위해 레오나르드 리차드슨(Leonard Richardson)은 REST API를 잘 적용하기 위한 4단계 모델을 만들었다.
앞서 이야기한 로이 필딩은 이 모델의 모든 단계를 충족해야 REST API라고 부를 수 있다고 주장했다. 그러나 실제로 엄밀하게 3단계까지 지키기 어렵기 때문에 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있다.
REST 성숙도 모델에 따르면, 0단계에서는 단순히 HTTP 프로토콜을 사용하기만 해도 되지만, 해당 API를 REST API라고 할 수는 없습니다. 0단계는 REST API를 작성하기 위한 기본 단계다.
1단계에서는 개별 리소스(Resource) 와의 통신을 준수해야 한다. REST API는 웹에서 사용되는 모든 데이터나 자원(Resource)을 HTTP URI로 표현합니다. 따라서 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야 하며 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 한다는 것이 1단계의 핵심이다.
2단계에서는 REST API는 CRUD에 맞는 적절한 HTTP 메서드를 사용해야 한다.
마지막 단계는 HATEOAS(Hypertext As The Engine Of Application State)라는 약어로 표현되는 하이퍼미디어 컨트롤을 적용한다. 요청은 2단계와 동일하지만, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야 한다. 링크 요소는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있다.
예를 들어 위와 같이 허준이라는 의사의 예약 가능 시간을 확인한 후에는 그 시간대에 예약을 할 수 있는 링크를 삽입하거나, 특정 시간에 예약을 완료하고 나서는 그 예약을 다시 확인할 수 있도록 링크를 작성해 넣을 수도 있다. 이렇게 응답 내에 새로운 링크를 넣어 새로운 기능에 접근할 수 있도록 하는 것이 3단계의 핵심이다.
만약 클라이언트 개발자들이 응답에 담겨 있는 링크들을 눈여겨본다면, 이러한 링크들은 조금 더 쉽고, 효율적으로 리소스와 기능에 접근할 수 있게 하는 요소가 될 수 있다.
Open API와 API Key
이러한 API들 중 자신이 가진 기능을 외부에서 사용할 수 있도록 공개한 Open API들이 있다.
예를 들어 공공데이터에 쉽게 접근할 수 있도록 정부는 Open API의 형태로 공공데이터를 제공하고 있다. 공공데이터 포털에 접속해 원하는 키워드를 검색하면, 해당 키워드와 관련된 API를 확인할 수 있다.
Open API는 누구나 사용할 수 있도록 열려있지만 무제한으로 이용할 수 있는 건 아니다. API마다 정해진 이용 수칙이 있고, 그 이용 수칙에 따라 제한사항(가격, 정보의 제한 등)이 있을 수 있다.
API Key
API key는 서버의 문을 여는 열쇠다. Open API를 이용하기 위해서는 대부분 API Key가 필요하다.
API Key가 필요한 경우에는 로그인한 이용자에게 자원에 접근할 수 있는 권한을 API Key의 형태로 제공하고, 데이터를 요청할 때 API key를 같이 전달해야 원하는 응답을 받을 수 있다.
레퍼런스