[Web] REST API

2021. 7. 3. 18:05

이번 포스팅은 네이버 D2 유튜브에 올라온 "그런 REST API로 괜찮은가" 영상을 토대로 작성하였다.

REST(REpresentational State Transfer) API란

REST API는 REST 아키텍처를 따르는 API이다. 문장을 하나씩 뜯어보자

REST → 분산 하이퍼미디어 시스템(ex. 웹)을 위한 아키텍처 스타일
아키텍처 스타일 → 제약 조건의 집합
API → API는 응용 프로그램에서 사용할 수 있도록, 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스

즉, REST에서 정의한 제약 조건을 모두 지켜야 REST를 따른다고 말할 수 있다는 것이다.

REST의 장단점

장점

1. Easy to use

REST API의 가장 큰 장점이라고 할 수 있다. 단순히 REST API 메시지를 읽는 것 만으로도 메시지가 의도하는 바를 명확하게 파악할 수 있다. 굳이 해당 메시지의 기능이 무엇인지 알기 위해 메뉴얼을 하나씩 읽어 볼 필요가 없게 만들어 준다.

HTTP 인프라를 그대로 사용하기 때문에, REST API 사용을 위한 별도의 인프라 구축을 요구하지 않는다. 그리고 Stateless한 특징 때문에 수행 문맥(Execution Context)가 독립적으로 진행됨으로써 이전에 서버(호스트)에서 진행된 내용들에 대해 클라이언트가 알 필요가 없으며, 이제까지 진행된 히스토리에 대해서도 알 필요가 없게 된다. 즉 해당 URI와 원하는 메소드 자체만 독립적으로 이해하면 된다.

2. Complete Seperation between Client and Server

클라이언트는 REST API를 이용하여 서버와 정보를 주고 받는다. 위에서 언급한 Stateless 한 특징에 따라, 서버는 클라이언트의 문맥을 유지할 필요가 없게 된다. 결국 클라이언트와 서버는 서로 신경쓰지 않으며 동작하게 된다. 서로에게 무관심한 이기적인 상황인 것이다. 하지만 실제로는 각자의 역할이 명확하게 분리되어 있다는 의미로 보는게 더 맞다.

이러한 장점으로 인해 플랫폼의 독립성 확장이라는 효과를 가져오고 HTTP 프로토콜만 지켜진다면 다양한 플랫폼에서 원하는 서비스를 쉽고 빠르게 개발/배포할 수 있게 된다.

3. Detail expression for specific data type

REST API는 헤더 부분에 URI 처리 메소드를 명시함으로써, 필요한 실제 데이터를 페이로드(바디)에 표현할 수 있도록 구성할 수 있는 기능을 제공한다. 이는 특정 메소드의 세부적인 표현 문구를 JSON, XML 등 다양한 언어를 이용하여 작성할 수 있다는 장점 뿐만 아니라, 간결한 헤더 표현을 통한 가독성 향상이라는 두마리 토끼를 잡는 효과를 가져다 주게 된다.

단점

1. Restriction of HTTP MethodREST

API는 HTTP 메소드를 사용하여 URI를 표현한다. 이러한 표현 방법은 다양한 인프라에서도 편리하게 사용할 수 있다는 장점을 주지만, 또 한편으로는 메소드 형태가 제한적 이라는 문제점을 가져오기도 한다.

2. Absence of Standard (표준의 부재)

REST API의 가장 큰 단점이라고 할 수 있는데, 바로 표준이 존재하지 않는다는 것이다.

이는 관리의 어려움과 좋은(공식화 된) API 디자인 가이드가 존재하지 않음을 의미하는데, 결국 REST API는 많은 사람들이 하나씩 쌓아올리는 ‘정당화 된 약속들’ 로 구성되고 움직이게 된다.

REST를 구성하는 스타일

Client-Server
Stateless
Cache
Uniform Interface
Layered System
Code-on-Demand (optional)

대체로 REST라고 부르는 것들은 위의 조건을 대부분 지키고 있다. 왜냐하면 HTTP만 잘 따라도 Client-Server, Stateless, Cache, Layered System은 다 지킬 수 있기 때문이다. Code-on-Demand는 서버에서 코드를 클라이언트로 보내서 실행할 수 있어야 한다는 것을 의미, 즉 자바스크립트를 의미한다. 이는 필수는 아니다.

단, 4번의 Uniform Interface는 잘 지켜지지 않는다고 한다.

Uniform Interface 제약 조건

Identification of resources
Manipulation of resources through representations
Self-descriptive messages
Hypermedia as the engine of application state(HATEOAS)

Identification of resources은 URI로 리소스가 식별되면 된다는 것이고, Manipulation of resources through representations는 representation 전송을 통해서 리소스를 조작해야된댜는 것이다. 즉, 리소스를 만들거나 삭제, 수정할 때 http 메시지에 그 표현을 전송해야된다는 것이다. 위 2가지 조건은 대부분 잘 지켜지고 있다. 하지만 문제는 아래 2개이다. 이 2가지는 사실 우리가 REST API라고 부르는 거의 모든 것들은 지키지 못하고 있다.

Uniform Interface의 세번째, 네번째 조건에 대해 알아보자

세번째 조건. Self-descriptive messages

Self-descriptive message라는 것은 메시지를 봤을 때 메시지의 내용으로 온전히 해석이 다 가능해야된다는 것이다.

예를 들어 아래와 같은 메시지가 있다고 해보자

GET / HTTP/1.1

단순히 루트를 얻어오는 GET 요청이다. 이 HTTP 요청 메시지는 목적지가 빠져있어서 Self-descriptive하지 못하다. 다음과 같이 수정할 수 있겠다.

GET / HTTp/1.1
Host: www.example.org

또 이런 것도 생각해볼 수 있다. 200 응답 메시지이며, JSON 본문이 있다.

HTTP/1.1 200 OK
[ { "op": "remove", "path": "/a/b/c" } ]

이것도 Self-descriptive 하지 않는데, 그 이유는 이걸 클라이언트가 해석하려고 하면, 어떤 문법으로 작성된 것인지 모르기 때문에 해석에 실패한다. 그렇기 때문에 Content-Type 헤더가 반드시 들어가야한다.

HTTP/1.1 200 OK
Content-Type: application/json
[ { "op": "remove", "path": "/a/b/c" } ]

Content-Type 헤더에서 대괄호, 중괄호, 큰따옴표의 의미가 뭔지 알게 되어, 파싱이 가능하여 문법을 해석할 수 있게 된다. 하지만 여전히 문제가 있다. op 값은 무슨 뜻이고, path가 무엇을 의미하는지는 알 수 없다.

HTTP/1.1 200 OK
Content-Type: application/json-patch+json
[ { "op": "remove", "path": "/a/b/c" } ]

이렇게 명시를 하면 완전해진다. 이 응답은 json-patch+json이라는 미디어 타입으로 정의된 메시지이기 때문에 json-patch라는 명세를 찾아가서 이해한 다음, 이 메시지를 해석을 하면 그제서야 올바르게 메시지의 의미를 이해할 수 있게 된다.

네번째 조건. HATEOAS

REST API의 완성도를 나타내는 RMM지표를 보면 3단계의 조건으로 HATEOAS를 확인할 수 있다.

"애플리케이션의 상태는 Hyperlink를 이용해 전이되어야 한다."

Hateoas란 REST Api를 사용하는 클라이언트가 전적으로 서버와 동적인 상호작용이 가능하도록 하는 것을 의미한다. 이러한 방법은 클라이언트가 서버로부터 어떠한 요청을 할 때, 요청에 필요한 URI를 응답에 포함시켜 반환하는 것으로 구현 가능하다.

이런 웹사이트가 있다고 해보자.

루트 홈페이지 → 글 목록 보기 GET → 글 쓰기 GET → 글 저장 POST → 생성된 글 보기 GET → 목록 보기 GET → 반복

이렇게 상태를 전이하는 것을 애플리케이션 상태 전이라고 하고, 이 상태 전이마다 항상 해당 페이지에 있던 링크를 따라가면서 전이했기 때문에 HATEOAS라고 할 수 있다. 말 그대로, 하이퍼 링크를 통한 전이가 되는 것이다.

HTTP/1.1 200 OK
Content-Type: text/html

<html>
<head> </head>
<body> <a href="/test"> test </a> </body>
</html>

이처럼 html은 하이퍼링크로 다음 상태로의 전이가 가능하기때문에 HATEOAS하다고 할 수 있다.

JSON의 경우에도 HATEOAS로 표현 가능하다.

{
    "account_id" : 12345,
    "balance" : "350,000"
}

이러한 JSON 표현이 있다고 했을때 이를 HATEOAS로 바꾸면

{
    "account_id" : 12345,
    "balance" : "350,000"
    "links" : {
    	{
            "rel" : "self",
            "href" : "http://localhost:8080/accounts/12345"
        },{
            "rel" : "withdraw",
            "href" : "http://localhost:8080/accounts/12345/withdraw"
        },{
            "rel" : "transfer",
            "href" : "http://localhost:8080/accounts/12345/transfer"
        }
    }
}

이렇게 표현될 수 있다.

HATEOAS를 사용함으로써 생기는 이점을 예를 들어 설명해보자면,

클라이언트가 GET 메소드로 URI 주소 '/member/1'를 호출한다면 사용자 ID가 1인 '사용자 정보'를 갖고온다고 가정해보자. 이때 동일한 URI로 DELETE 메소드를 호출 할 경우 사용자 삭제가 가능하고, PUT 메소드를 호출할 경우 업데이트라고 한다면 일일히 클라이언트 쪽에 알려줘야 한다는 번거로움이 발생한다. 이것을 줄이고자 호출한 URI로부터 연관된 REST API 주소 정보들을 함께 보내주는 역할을 하는 것이 HATEOAS 이다. 그럼으로써 클라이언트는 서버와 상호 작용하는 방법에 대한 사전 지식이 거의 또는 전혀 필요없이 사용 할 수 있게 되는 것이다.