REST는 REpresentational State Transfer의 약자로 2000년도 Roy Fielding의 박사학위 논문에서 최초로 소개되었다. Roy Fielding은 HTTP의 주요 저자중 한사람으로 REST API는 웹 아키텍처의 우수성을 최대한 활용하기 위해 만들어진 API다. 요즘은 웹 서비스뿐 아니라 여러 컴포넌트들로 구성되어 있는 서비스들을 하나로 묶어야 하는 경우에도 많이 사용된다. 따라서 REST API에 대해 잘 알고 있으면 도움이 많이 된다.
REST란?
REST를 다음과 같이 정의할 수 있다.
HTTP URI로 잘 표현된 리소스에 대한 행위를 HTTP Method로 정의한다. 리소스의 내용은 json, xml, yaml 등의 다양한 표현 언어로 정의된다.
'무엇을 어떻게 한다'로 잘 정의된 API를 REST API라고 할 수 있다. 이 때, 무엇을에 해당하는 것은 HTTP URI로 정의된 리소스이며, 어떻게 한다는 것은 HTTP Method + Payload라고 할 수 있다. 즉, HTTP URI로 정의된 리소스에 대해서 HTTP Method를 수행하는 것을 REST API라고 한다.
리소스(Resource)
REST API가 무언가를 할 대상이다. 리소스는 JSON, XML 같은 문서일 수도 있고, JPG 같은 이미지 파일일 수도 있으며, MP4 같은 비디오일 수도 있다.
이런 리소스드른 URI에 의해 표현된다. URI는 Uniform Resource Identifier의 약자로 HTTP 혹은 FTP 프로토콜로 표현할 수 있는 유일한 주소를 의미한다. 우리가 웹 서핑에서 흔히 사용하는 URL은 URI의 한 종류로 웹 상에서 존재하는 HTTP 문서의 위치를 나타내는데 사용된다. URL을 이용해 웹에서 특정 문서를 찾아가는 것처럼 URI를 이용해 특정 리소스를 가리킬 수 있다.
예를 들어 https://hbase.tistory.com/image/example.jpg 같은 URI는 특정 도메인의 특정 위치에 있는 이미지 파일을 식별하기 위해 사용된다.
메소드 (Method)
REST API에서는 리소스에 대한 행위가 일관되게(Uniform) 정의된다. REST API에서 사용되는 메소드는 HTTP Method로 POST, GET, PUT, PATCH, DELETE 등이 있다. 이들을 각각 CRUD(CReate, Update, Delete)에 다음과 같이 대응시킬 수 있다.
| HTTP Method | CRUD 연산 |
| POST | create |
| GET | read |
| PUT | update / replace |
| PATCH | update / modify |
| DELETE | delete |
대표적으로 사용되는 HTTP Method가 이렇고 HEAD, TRACE, OPTIONS, CONNECT 등의 메소드가 더 있다. HTTP 메소드에 대한 내용은 RFC7231, RFC5789 를 참고하자.
리소스와 메소드는 다음과 같이 사용할 수 있다.
GET https://hbase.tistory.com/image/example이런 요청은 https://hbase.tistory.com/image/example.jpg 라는 리소스에 대해 GET 요청을 하겠다는 의미로 이미지 파일을 읽어오라는 뜻이다.
이처럼 HTTP Method에 리소스의 URI를 함께 사용해서 어떤 리소스에 뭘 하라라고 전달한다. 여기에 부가적인 정보들을 더 붙여서 요청을 만들게 된다.
GET https://hbase.tistory.com/images/example HTTP/1.1 Accept:image/jpgexample이라는 파일을 읽어오는데 HTTP/1.1 프로토콜을 사용하며 파일의 포맷은 jpg 이미지 파일이라는 정보를 전달할 수 있다.
표현 (Representation)
HTTP Method만으로 원하는 동작을 모두 표현할 수 있는 것은 아니다. 예를 들어 새로운 유저를 생성하라는 요청을 REST API로 표현하면 다음과 같다.
POST https://hbase.tistory.com/users/newuser호스트에 있는 users에 새로운 사용자인 newuser를 추가하라는 REST API다. 사용자를 생성할 때에는 이름뿐 아니라 직업, 나이, 성별 같은 정보들이 필요할 수도 있다. 이런 부가적인 정보를 모두 URI에 구성하기는 힘들다. URI가 지나치게 길어지고, API의 수정이 어려워지는 등의 문제가 있다.
따라서 HTTP Method는 Payload 혹은 Method Body를 통해 이런 정보들을 받는다.
POST https://hbase.tistory.com/users Content-Type:application/json
{
"username":"newuser",
"age":27
}POST 요청의 헤더에 Content-Type으로 JSON 문서가 페이로드로 전달됨을 명시하고, JSON 문서를 함께 전달하는 식으로 REST API를 구성할 수 있다.
REST API 특징
Uniform
REST API는 리소스에 상관없이 동일한 API 메소드를 통해 처리된다. 이미지 파일이나 문서 파일이나 동일한 메소드로 처리되므로 리소스의 타입과 상관없이 일관된 형태로 처리되어진다.
Stateless
REST API를 제공하는 서버측에서는 수행의 컨텍스트를 저장하지 않는다. 즉, 클라이언트가 직전에 어떤 요청을 보냈었는지 관련된 정보를 저장하지 않고 각 REST 요청들이 독립적으로 처리가 된다. 요청간 컨텍스트가 필요하다면 클라이언트가 이를 기억했다가 관련된 정보를 서버에 전달해줘야한다. 즉, 서버는 세션을 유지하지 않는다.
Cacheable
HTTP 프로토콜을 사용하기 때문에 기존 웹 인프라를 그대로 사용할 수 있다. 웹 브라우저에서 HTTP 캐시를 이용하는 등의 동작이 그대로 사용가능하며, 이를 통해 동일한 URI에 대한 요청을 매번 서버에 날리지 않고 클라이언트의 HTTP 캐시에서 가져올 수 있다.
Self-descriptive
REST API는 그 자체로 쉽게 이해할 수 있다. 별도의 주석이나 문서가 없어도 특정 REST API가 무엇을 하는 것인지 쉽게 이해할 수 있어야 한다.
Client-Server Architecture
REST API로 연결된 두개의 컴포넌트는 클라이언트와 서버로 역할이 명확히 갈린다. 서버는 클라이언트에게 API를 제공하기만하면 되고, 실행 컨텍스트는 클라이언트에서 유지해야한다. 이 때문에 전반적인 서비스 아키텍처가 심플해진다.
Layered System
REST API는 Multi-layer로 구성될 수 있다. 클라이언트는 대상 서버에 직접 붙었는지 중간에 존재하는 서버와 통신하는지 알 수 없다. 이 중간에 존재하는 서버를 이용하여 Security관리 Encrypt, load balancing 등을 수행할 수 있어 확장성 및 보안 향상이 가능하다.
RESTful 하다
이러한 REST API의 설계 의도를 정확하게 지켜주는 API를 'RESTful 하다'라고 부른다. RESTful한 API는 구성요소들의 역할이 명확하게 분리되어 있어야 한다. URI는 자원을 정확하고 인식하기 편하게 표현하는데에 집중하고, 자원에 대한 행위는 Uniform하게 HTTP 메소드를 통해 정의를 한다. 나머지 페이로드는 Json이나 XMl, YAML 같은 언어를 이용하여 별도로 정의한다.
일반적으로 RESTful한 API를 설계하기 위해서 URI를 잘 정의하는 것이 중요하다. URI의 설계 원리는 일반적으로 다음과 같다.
1) 슬래시 '/'는 계층 관계를 나타내는데 사용한다
위의 예제에서 사용자를 나타내는 URI에서 슬래시 문자를 사용했었다.
https://hbase.tistory.com/users/newuserhttps://hbase.tistory.com이라는 호스트와 users는 계층 관계다. users는 사용자 리소스를 모아둔 컬렉션으로 볼 수 있으며, users 컬렉션 하위에는 newuser를 비롯한 여러 유저들이 존재한다. 이 역시 계층관계이며 URI에서 슬래시(/) 문자를 통해 구분한다. 계층은 항상 바닥에서 끝나야 하므로 URI는 슬래시로 끝나지 않아야 한다.
URI에서 계층 관계를 표현할 때, 여러 리소스들의 집합 개념인 컬렉션은 복수(-s)를 이용하고, 개개의 리소스 엘리먼트(element)는 단수를 이용하여 표현하는 것이 가독성을 높이는데 도움이 된다.
2) URI는 가독성이 중요하다
가독성을 위해 URI에는 Under score(_) 문자의 사용을 자제해야한다. 특정 폰트나 문자에서 Under Score 문자가 다른 문자와 섞여서 제대로 보이지 않는 경우가 있기 때문이다.
또 한, URI는 호스트를 제외한 나머지에 대해서 소문자를 사용하는 것이 좋다. URI는 RFC 3986에서 호스트를 제외한 나머지에 대해서 대소문자를 구별하도록 정의되어 있기 때문에 명확한 정의를 위해 소문자로 통일하는 것이 좋다. 예를 들어, Users와 users는 서로 다른 컬렉션이다. 하지만 이름만으로는 왜 저 두개의 컬렉션이 구분되어야하는지 알수 없기 때문에 모호성이 추가된다. 따라서 소문자로 통일해서 사용하는 것을 추천한다.
3) 파일 확장자는 URI에 포함시키지 않는다
URI에는 일반적으로 파일 확장자를 포함시키지 않는다.
https://hbase.tistory.com/images/example.jpg위와 같은 URI 표현보다는 다음과 같은 표현이 더 적절하다.
https://hbase.tistory.com/images/example accept:image/jpg이유는 jpg 같이 잘 알려진 확장자는 어떤 파일인지 한눈에 알아볼 수 있지만 특별한 확장자의 경우 어떤 파일인지 알아보기 어렵기 때문이다. 예를 들어 hwp 파일이나 alz 확장자를 갖고 있는 파일은 우리나라 사람이라면 한글 문서와 알집 파일임을 알 수 있지만 외국 사용자는 뭔지 모르기 때문이다. 파일의 포맷이 뭔지 알아볼 수 있게 URI 풀어쓰는게 좀 더 좋은 설계라고 할 수 있다.
4) URI는 명사 위주로 쓰자
URI에 동사가 들어가면 HTTP 메소드와 URI를 분리한 애초의 목적이 모호해진다.
GET https://hbase.tistory.com/users/delete-olduser이처럼 URI에 동사를 사용해버리면, GET 메소드를 보냈지만 이 메시지의 의도가 olduser를 지우라는 것으로 해석될 가능성이 있다. 메시지에 모호성이 추가되기 때문에 바람직한 설계는 아니다.
이 밖에도 다양한 REST API 설계 가이드가 있다. 정확하게 이렇게 써야한다는 문법이나 강력한 표준이 없기 때문에 RESTful한 API 설계외 그렇지 않은 설계가 혼재하게 된다.
REST API 장점
1) 쉬운 사용법
REST API는 사용이 쉽다. REST API 메시지 자체를 그냥 읽기만 하는 것으로도 메시지의 본래 의도를 파악할 수 있을 정도로 쉽게 이해가 된다. 또 한 기존 HTTP 인프라를 그대로 이용하기 때문에 REST를 사용하기 위해 별도의 인프라를 요구할 필요가 없다.
또 한 Stateless이기 때문에 세션과 요청 내용이 연관되지 않기 때문에 요청이 수행 컨텍스트(Context)에 독립적이다. 따라서 이해하기 쉽고, 사용하기 쉽다.
2) Client-Server의 명확한 분리
클라이언트는 REST API를 통해 서버와 정보를 주고 받는다. 서버 입장에서는 클라이언트의 수행 컨텍스트를 유지할 필요가 없다. 즉, 별도의 세션 정보를 유지할 필요가 없고, 단지 클라이언트에서 요청한 내용만 처리해서 응답하면 된다. 이는 클라이언트와 서버의 역할을 명확하게 분리해서 REST API의 제공과 사용으로 분리하여 개발할 수 있게 한다.
심지어 HTTP 프로토콜만 서비스하면 되기 때문에 플랫폼과도 독립적이어서 멀티 플랫폼 상황에서 서비스를 쉽게 개발할 수 있게 해준다. (리눅스 서버에 떠 있는 웹 서버에 윈도우에서 동작하는 웹 브라우자가 붙어서 동작할 수 있다.)
3) 원하는 데이터 표현의 사용이 가능
REST API는 헤더부분에 URI에 대한 처리 메소드를 명시하고, 필요한 실제 데이터는 body부분에 표현하도록 분리시켰다. 페이로드부분을 JSON, XML, YAML 등 원하는 표현 언어로 사용할 수 있다는 장점이 있다.
REST API 단점
1) HTTP Method의 한계
REST API는 HTTP 메소드를 이용하여 URI에 대한 행위를 정의한다. 따라서 간단한 수준의 메소드만 지원할 수 있다. 예를 들어 '메일을 보낸다.'라는 행위는 단일 메소드로 구현하기 쉽지 않은 일이다.
2) 표준의 부재
REST API는 API 설계 가이드일 뿐이지 명시적인 표준이 아니다. 따라서 관리가 어렵고, 좋은 API 디자인에 대한 가이드가 쉽지 않다. 어떤 가이드는 특정한 REST API에는 맞지만 또 다른 곳에는 맞지 않을 수 있다.
3) RDBMS와의 어색한 관계
REST API를 RDBMS에 적극적으로 사용하기 위해서는 RESTful 한 테이블 구조가 필요하게 되는데, 이것보다는 NoSQL쪽이 더 잘 맞는 추세다.
댓글