REST API/RMM

유슬기·2023년 1월 31일

프론트엔드

목록 보기

36/64

REST API

REST API의 탄생

REST API에서 REST는 “Representational State Transfer”의 약자로서 2000년도에 로이 필딩 (Roy Fielding)의 박사학위 논문에서 최초로 소개되었다. 로이 필딩은 HTTP의 주요 저자 중 한 사람으로 그 당시 웹(HTTP) 설계의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하며 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했다고 한다.

REST의 구성요소

REST의 구성요소는 크게 resource, method, message 세 가지로 구성된다.

예를 들어 “이름이 Curry인 사용자를 생성한다” 라는 호출이 있을 때

“사용자”는 생성되는 resource, “생성한다” 라는 행위는 method, “이름이 Curry인 사용자”는 message가 된다.

자원(resource)

모든 자원에는 고유한 ID가 존재하고, 이 자원은 서버에 존재한다.

DB 안에 들어가 있는 데이터 하나하나를 의미한다. (또는, 이미지 하나하나를 의미)

REST는 자원에 접근할 때 URI를 이용하여 자원을 명시하고, 구분할 수 있다.
- 여기서 URI는 자원의 위치를 나타내는 일종의 식별자이다.
메서드(method)

클라이언트는 HTTP Method(GET, POST, PUT, DELETE 등)를 이용하여 지정한 자원에 대한 조작을 요청한다.
- GET: 해당 리소스를 조회(Read)
- POST: 해당 리소스를 생성(Create)
- PUT: 해당 리소스를 교체(Update)
- PATCH: 해당 리소스를 수정(Update)
  - PUT 메서드와 PATCH 메서드를 구분하여 사용해야 함. PUT은 교체, PATCH는 수정의 용도로 사용한다.
- DELETE: 해당 리소스를 삭제(Delete)
위와 같은 연산을 CRUD 연산이라고 한다.
메시지(message)

클라이언트가 서버에게 자원에 대한 조작을 요청하면, 서버는 이에 대한 적절한 응답(Representation)을 보낸다.

메시지는 HTTP header, body, 응답 상태 코드 등으로 구성되어 있다. 간단하게 설명하자면 header에는 body에 어떤 형식으로 데이터가 담겼는지 표시하고, body는 자원에 대한 정보를 JSON, XML 등으로 전달한다. 응답 상태 코드는 200~500 사이의 숫자로 클라이언트의 요청에 대한 상태를 나타내 준다.

REST API란

REST API는 REST를 통해서 서비스 API를 구현한 것을 말한다.

REST의 구체적인 개념은 클라이언트와 서버 사이에서, HTTP URI를 통해 자원을 명시하고, HTTP Method (POST, GET, DELETE, PUT 등)를 통해 해당 자원에 대한 조작을 요청하고, 이에 대한 응답을 받는 것을 의미한다.

REST의 특징

Client - Server(클라이언트-서버) 구조

자원이 있는 쪽이 서버, 자원을 요청하는 쪽이 클라이언트가 된다. 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보)등을 직접 관리하고, 서버는 API를 제공하고 비즈니스 로직 처리 및 저장을 책임진다.

각각의 역할이 확실히 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로간 의존성이 줄어들게 된다.
Stateless(무상태성)

HTTP 프로토콜은 기본적으로 무상태이다. REST 역시 HTTP를 기본으로 하기 때문에 무상태이다. 여기서 무상태란 클라이언트의 상태(State)를 서버에 저장하지 않는다는 뜻이다.

서버는 클라이언트의 요청을 완전히 별개의 것으로 인식하고 처리한다. 따라서 이전의 요청이 다음의 요청에 연관되지 않는다. 이를 통해 서버의 처리 방식에 일관성을 부여하고 부담이 줄어들게 된다.
Cacheable(캐시 처리 가능)

REST는 HTTP라는 기존 웹표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용이 가능하다. 따라서 HTTP의 캐싱 기능을 적용할 수 있다.
즉, 대량의 요청을 효율적으로 처리하기 위한 캐시를 사용할 수 있다. 캐시 사용을 통해 응답 시간이 빨라지고 성능, 서버의 자원 이용률을 향상할 수 있다.

캐싱 처리는 GET 요청에서 주로 처리된다. (POST, PUT으로도 가능은 하나, 잘 사용하지 않는다.)
HTTP 프로토콜 표준에서 사용하는 Last-Modified태그나 E-Tag를 이용하면 캐싱 구현이 가능하다.
Layered System(계층형 구조)

클라이언트는 REST API 서버만 호출한다. REST 서버는 다중 계층으로 구성될 수 있다.

API 서버는 순수 비즈니스 로직을 수행하고 그 앞단에 보안, 로드 밸런싱, 암호화, 사용자 인증 등을 추가하여 구조상의 유연성을 줄 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 한다.
Self-descriptiveness (자체 표현 구조)

REST의 또 다른 큰 특징 중 하나는 REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조로 되어 있다는 것이다.
Uniform Interface(인터페이스 일관성)

Uniform Interface는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 말한다.

URI로 지정한 자원에 대한 조작을 통일되고 한정적인 인터페이스로 수행한다. HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다. 따라서 특정 언어나 기술에 종속되지 않는다.

REST의 장단점

장점

언어와 플랫폼에 독립적이다.
REST API 메시지가 의도하는 바를 명확하게 나타내 의도를 쉽게 파악할 수 있다.
REST가 지원하는 프레임워크나 언어 등 도구들이 없어도 구현 가능하다.
HTTP를 사용하므로 기존 웹 인프라 사용이 가능하다.
서버와 클라이언트의 역할을 명확하게 분리한다.
여러 가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다.

단점

HTTP 프로토콜만 사용 가능하다.
p2p 통신 모델을 가정하여 둘 이상을 대상으로 하는 분산 환경에 유용하지 않다.
보안, 정책 등에 대한 표준이 없다.

REST API 성숙도 모델(REST API 디자인 가이드)

REST API 설계 시에는 몇 가지 지켜야 할 규칙들이 있다. 성숙도 모델은 총 4단계로 나누어져서 각 단계의 조건에 만족할 수록 REST API에 가까워진다고 한다.

로이 필딩이 논문에서 제시한 REST 방법론을 보다 더 실용적으로 적용하기 위해 레오나르드 리차드슨(Leonard Richardson)은 REST API를 잘 적용하기 위한 4단계 모델을 만들었다.
로이 필딩은 이 모델의 모든 단계를 충족해야 REST API라고 부를 수 있다고 주장했다. 그러나 실제로 엄밀하게 3단계까지 지키기 어렵기 때문에 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있고, 이런 경우를 HTTP API 라고도 부른다.

RMM

0단계

단순히 HTTP 프로토콜을 사용하기만 해도 된다. 0단계는 REST API를 작성하기 위한 기본 단계이다.

(물론 이 경우, 해당 API를 REST API라고 할 수는 없다.)

“허준”이라는 의사의 예약 가능한 시간을 확인하고, 특정 시간에 예약하는 상황을 예시로 들어보겠다.

위 예시에서는 HTTP 프로토콜을 사용하고 있다. 이렇듯 단순히 HTTP 프로토콜을 사용하는 것이 REST API의 출발점이다.

1단계

개별 리소스(Resource)와 통신을 준수한다.

모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야하며, 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 한다.

엔드포인트 작성 시에는 동사, HTTP 메서드, 혹은 어떤 행위에 대한 단어 사용은 지양하고, 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직한 방법이다.

더불어 요청에 따른 응답으로 리소스를 전달할 때에도 사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환해야 한다.

예를 들어, 유카레 환자가 허준 의사에게 9시에 예약을 진행하였으나 해당 시간이 마감되어 예약이 불가능하다고 가정할 때, 아래와 같이 리소스 사용에 대한 실패 여부를 포함한 응답을 받아야 한다.

Response

HTTP/1.1 409 Conflict
[header 생략]
{
	"appointmentFailure": {
		"slot": { "id": 123, "doctor": "허준", "start": "09:00", "end": "12:00" },
		"patient": "유카레",
		"reason": "해당 시간은 이미 예약되어 있습니다"
}

2단계

CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둔다.

CRUD: Create, Read, Update, Delete

GET: 해당 리소스를 조회(Read)

POST: 해당 리소스를 생성(Create)

PUT: 해당 리소스를 교체(Update)

PATCH: 해당 리소스를 수정(Update)

PUT 메서드와 PATCH 메서드를 구분하여 사용해야 함. PUT은 교체, PATCH는 수정의 용도로 사용한다.

DELETE: 해당 리소스를 삭제(Delete)

예약 가능한 시간을 조회(Read)하기 위해 GET 메서드를 사용하여 요청한다. 이때 GET 메서드는 body를 가지지 않기 때문에 query parameter(여기에선 ?date=2022-08-10)를 사용하여 필요한 리소스를 전달한다.
응답은 해당 리소스를 보내준다.
특정 시간에 예약을 생성(Create)하기 위해 POST 메서드를 사용하여 요청한다.
응답은 새롭게 생성된 리소스를 보내주기 때문에, 응답 코드는 201 Created 로 명확하게 작성, 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인할 수 있도록 작성한다.

HTTP 메서드 사용 규칙

GET 메서드는 서버의 데이터를 변화시키지 않는 요청에 사용해야 한다.
POST 메서드는 요청마다 새로운 리소스를 생성하고 PUT 메서드는 요청마다 같은 리소스를 반환한다.
이렇게 매 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 한다. 그렇기 때문에 멱등성을 가지는 메서드 PUT과 그렇지 않은 메서드POST는 구분하여 사용해야 한다.
PUT 메서드와 PATCH 메서드도 구분하여 사용해야 한다. PUT은 교체, PATCH는 수정의 용도로 사용한다.

3단계

HATEOAS, 하이퍼미디어 컨트롤(Hypermedia As The Engine Of Application State)을 적용한다.

요청은 2단계와 동일하나, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성한다.
응답 내에 새로운 링크를 넣어 새로운 기능에 접근할 수 있도록 하는 것이 3단계의 핵심 포인트이다.

클라이언트 개발자들이 응답에 담겨 있는 링크들을 눈여겨본다면, 이러한 링크들은 조금 더 쉽고 효율적으로 리소스와 기능에 접근할 수 있게 하는 요소가 될 수 있다.

응답에 들어가게 되는 링크 요소: 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함한다.

예약 가능 시간을 확인하는 요청을 보냈을 때, 그 시간대에 예약을 할 수 있는 링크를 삽입하여 응답
특정 시간에 예약을 생성하는 요청을 보냈을 때, 그 예약을 다시 확인할 수 있는 링크나 예약을 취소할 수 있는 링크를 삽입하여 응답

Open API와 API Key

Open API

Open API는 개방된 API를 의미한다. 이는 누구나 사용할 수 있고, 다양한 소프트웨어 시스템이나 웹 서비스에서 데이터나 기능을 쉽게 가져갈 수 있도록 공개된 API를 의미한다. 그러나 "무제한으로 이용할 수 있다"라는 의미는 아니다. API마다 정해진 이용 수칙이 있고, 그 이용 수칙에 따라 제한사항(가격, 정보의 제한 등)이 있을 수 있다.
Open API는 개발자들이 새로운 애플리케이션을 만들거나 기존의 애플리케이션에 기능을 추가하는데 편리하며, 결과적으로 새로운 서비스나 애플리케이션이 더 빠르고 쉽게 개발되는 결과를 가져온다.

Open API를 간단하게 경험해 볼 수 있는 대표적인 페이지는 Open Weather Map이라는 웹 사이트에서 제공하는 날씨 API이다.

API Key

API를 이용하기 위해서는 API Key가 필요하다.(가끔 API key가 필요하지 않은 경우도 있다.)
API Key가 필요한 경우에는 로그인한 이용자에게 자원에 접근할 수 있는 권한을 API Key의 형태로 제공하고, 데이터를 요청할 때 API key를 같이 전달해야 원하는 응답을 받을 수 있다.

API Key는 컴퓨터 프로그램에 의해 전달되는 코드로, 호출되는 프로그램을 식별하고 그것과 관련된 리소스(예를 들어 데이터 또는 서비스)에 액세스하도록 하는 것을 목적으로 한다. API Key는 API가 어떻게 사용되고 있는지 추적하고 제어하는 데 사용되며, 예를 들어 API의 악용 또는 나쁜 사용을 방지하는 데 사용된다.
API Key는 고유하고 생성이 간단하고 사용이 쉬운 특징이 있어 API 액세스 관리 시 자주 사용된다.