[HTTP/네트워크] REST API

KIM DA MI·2023년 3월 29일

REST API RMM api key http open API

HTTP/네트워크

목록 보기

5/7

1. REST API이란?

REST API에서 REST란 "Representational State Transfer"의 약자이다.

이 용어는 로이 필딩(Roy Fielding)의 박사학위 논문에서 처음 소개되었으며,
웹(HTTP)의 장점을 최대한 활용할 수 있는 아키텍처로 정의되었다.

REST API는 웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고,
HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식을 사용한다.

`REST API`는 왜 필요할까?

REST API를 이해하기 쉽게 설명하자면, 식당에서 손님이 메뉴판을 보고 주문하는 것과 비슷하다.

예를 들어 어떤 식당의 손님이 식사 혹은 음료를 주문한다고 가정해보자.
메뉴판을 받았을 때 메뉴판의 상태가 아래 사진과 같다면 어떨까?
- 알아보기도 어렵고, 주문하기도 어려울 것이다. 🙁

이렇듯 클라이언트와 서버 사이에도 데이터와 리소스를 요청하고, 요청에 따른 응답을 전달하기 위한 메뉴판이 필요하다.

메뉴판을 보고 클라이언트는 식당에서 식사를 주문하듯 서버에 요청하고, 이에 대한 응답을 메뉴판에 있는 사진이나 음식에 대한 설명처럼 다시 서버에서 클라이언트로 전송하게 된다.

따라서 HTTP 프로토콜을 기반으로 요청과 응답에 따라 리소스를 주고받기 위해서는 알아보기 쉽고 잘 작성된 메뉴판이 필요한데, 이 역할을 API가 수행해야 하므로 모두가 잘 알아볼 수 있도록 작성하는 것이 중요하다.

➡ 그렇다면 어떻게 해야 적절한 REST API를 디자인할 수 있을까?

`REST API`를 디자인하는 방법

REST API를 작성할 때는 몇 가지 지켜야 할 규칙들이 있다.

로이 필딩이 논문에서 제시한 REST 방법론을 보다 더 실용적으로 적용하기 위해 레오나르드 리차드슨(Leonard Richardson)은 REST API를 잘 적용하기 위한 4단계 모델을 만들었다.

리차드슨의 REST 성숙도 모델을 구조화하면 다음과 같다.
- REST 성숙도 모델은 총 4단계(0~3단계)로 나누어진다.

로이 필딩은 이 모델의 모든 단계를 충족해야 REST API라고 부를 수 있다고 주장했지만 실제로 엄밀하게 3단계까지 지키기는 어렵다.

때문에 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있고, 이런 경우를 HTTP API 라고도 부른다.

2. REST 성숙도 모델

🥚 REST 성숙도 모델 - 0단계

REST 성숙도 모델에 따르면, 0단계에서는 단순히 HTTP 프로토콜을 사용하기만 해도 된다.

물론 이 경우, 해당 API를 REST API라고 할 수는 없으며, 0단계는 REST API를 작성하기 위한 기본 단계이다.

"어벤져스-엔드게임"이라는 영화의 예매 가능한 시간을 확인하고, 어떤 특정 시간에 예매하는 상황을 예로 들어 보자.
위 예시에서는 HTTP 프로토콜을 사용하고 있는 것을 확인할 수 있다.
이렇듯 단순히 HTTP 프로토콜을 사용하는 것이 REST API의 출발점이다.

🐣 REST 성숙도 모델 - 1단계

REST 성숙도 모델의 1단계는 개별 리소스(Resource)와의 통신을 위해 URI로 표현해야 한다.

이를 위해 각 리소스에 대한 엔드포인트를 사용하여 요청과 응답을 구분해야 한다.

앞서 0단계 예시에서는 모든 요청을 /appointment 엔드포인트로 처리하였지만,
1단계에서는 요청하는 리소스에 따라 각각 다른 엔드포인트를 사용해야한다.

이를 준수하지 않으면 REST API로서의 특징을 충족시키지 못하게 된다.

위의 예시에서 예매 가능한 시간 확인이라는 요청의 응답으로 받게 되는 자원(리소스)은
"어벤져스-엔드게임"이라는 영화의 예매 가능한 시간대이다.
그렇기 때문에 요청 시 /movie/어벤져스-엔드게임이라는 엔드포인트를 사용한 것을 볼 수 있다.

그뿐만 아니라, 특정 시간에 예매하게 되면, 실제 slots라는 리소스의 123이라는 id를 가진 리소스가 변경되기 때문에, 하단의 특정 시간에 예매이라는 요청에서는 /slots/123으로 실제 변경되는 리소스를 엔드포인트로 사용하였다.

이렇듯, 어떤 리소스를 변화시키는지 혹은 어떤 응답이 제공되는지에 따라 각기 다른 엔드포인트를 사용하기 때문에, 적절한 엔드포인트를 작성하는 것이 중요하다.
엔드포인트 작성 시에는 동사, HTTP 메서드, 혹은 어떤 행위에 대한 단어 사용은 지양하고, 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직한 방법이다.

더불어 요청에 따른 응답으로 리소스를 전달할 때에도 사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환해야 한다. 예를 들어, 김철수가 어벤져스-엔드게임을 9시에 예매를 진행하였으나 해당 시간의 좌석이 모두 매진되어 예매가 불가능하다고 가정할 때, 아래와 같이 리소스 사용에 대한 실패 여부를 포함한 응답을 받아야 한다.

🐥 REST 성숙도 모델 - 2단계

REST 성숙도 모델 2단계에서는 CRUD(Create, Read, Update, Delete)에 맞는 HTTP 메서드를 사용하는 것이 중요하다.

예를 들어, 예매 가능한 시간 조회(READ)와 예매 생성(CREATE)은 각각 GET과 POST 메서드를 사용해야 한다.

이때 GET 메서드는 query parameter를 사용하여 요청하고, POST 메서드는 요청 후 생성된 리소스를 응답으로 보내주며, 이때 응답 코드는 201 Created이어야 한다.

Location 헤더를 통해 클라이언트가 관련 리소스를 확인할 수 있도록 해야 REST 성숙도 모델 2단계를 충족하는 것이다.

HTTP 메서드를 사용할 때 유의해야 할 규칙

GET 메서드는 서버의 데이터를 변화시키지 않는 요청에 사용해야 한다.

POST 메서드는 요청마다 새로운 리소스를 생성하고 , PUT 메서드는 요청마다 같은 리소스를 반환한다. ( 매 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 한다.)

멱등성을 가지는 PUT과 그렇지 않은 DELETE 메서드는 구분하여 사용해야 한다.

PUT은 교체, PATCH 는 수정의 용도로 사용하기 때문에 서로 구분하여 사용해야 한다.

REST 성숙도 모델의 2단계까지 적용하면 대체적으로 잘 작성된 API라 할 수 있으며,
모범적인 API 디자인조차도 REST 성숙도 모델의 3단계까지 적용한 경우는 드물다.
따라서 3단계까지 무조건적으로 모두 적용해야 하는 것은 아니다.

🐓 REST 성숙도 모델 - 3단계

마지막 3단계는 REST 성숙도 모델의 마지막 단계인 HATEOAS(Hypermedia As The Engine Of Application State)를 적용하는 단계이다.

이 단계에서는 응답에 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야 한다.

이때 응답에 들어가는 링크 요소는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있다.
- 예를 들어 영화 예매 가능 시간을 확인한 후에는 그 시간대에 예매를 할 수 있는 링크를 삽입하거나, 특정 시간에 예매를 완료하고 나서는 그 예매를 다시 확인할 수 있도록 링크를 작성해 넣을 수 있다.