REST API의 이해

REST API의 이해

REST 는 웹의 창시자중의 한 사람인 Roy Fielding의 2000년 논문에 의해서 소개됨. 현재의 아키텍쳐가 웹의 본래 설계의 우수성을 많이 사용하지 못하고 있다고 판단하여 웹의 장점을 최대한 활용할 수 있는 네트워크 기반의 아키텍쳐를 소개한 것이 Representational safe transfer (REST)이다.

REST의 기본

• REST는 요소로는 크게 리소스, 메서드, 메세지 3 가지 요소로 구성됨
• 예를 들어서 “이름이 Terry 인 사용자를 생성한다” 라는 호출이 있을 때, “사용자”는 생성되는 리소스, “생성한다” 라는 행위는 메서드 그리고 “이름이 Terry인 사용자”는 메시지가 된다.

이를 REST 형태로 표현해보면 다음과 같다.

HTTP POST, http://myweb/users/
{
    "users":{
        "name":"terry"
    }
}

• 생성한다의 의미를 갖는 메서드는 HTTP Post 메서드가 되고, 생성하고자 하는 대상이 되는 사용자라는 리소스는http://myweb/users 라는 형태의 URI로 표현이 되며, 생성하고자 하는 사용자의 디테일한 내용은 JSON 문서를 이용해서 표현됨

*URI (Uniform Resource Identifier):프로토콜, 머신어드레스, 포트번호를 제외한 나머지 경로

REST의 리소스

REST는 리소스 지향 아키텍쳐 스타일이라는 정의 답게 모든 것을 리소스(명사)로 표현을 하며, 각 세부 리소스에는 id를 붙임. 즉, 사용자라는 리소스 타입을 http://myweb/users라고 정의했다면, terry 라는 id를 갖는 리소스는 http://myweb/users/terry 라는 형태로 정의함

REST의 리소스가 명사의 형태를 띄다 보니, 명령(Operation)성의 API를 정의함에 있어 혼돈이 올 수 있음.
예를 들어서 “Push 메세지를 보낸다”는 보통 기존의 RPC(Remote Procedure Call)이나 함수성 접근에서는 /myweb/sendpush 형태로 잘못 정의될 수 있지만, 이러한 동사형을 명사형으로 바꿔서 적용해보면 리소스 형태로 표현면 됨. “Push 메시지 요청을 생성한다.” 라는 형태로 정의를 변경하면, API 포맷은 POST /myweb/push 형태로 표현 가능. 가능하면 리소스 기반의 명사 형태로 정의를 하는게 REST 형태의 디자인.

REST API의 간단한 예제

1. 사용자 생성

http://myweb/users 라는 리소스를 이름은 terry, 주소는 seoul 이라는 내용(메세지)로 HTTP Post를 이용해서 생성

HTTP POST, http://myweb/users/
{
    "name":"terry",
    "address":"seoul"
}

2. 사용자 조회

생성된 리소스 중에서 http://myweb/users 라는 사용자 리소스중에, id가 terry인 사용자 정보를 조회

HTTP Get, http://myweb/users/terry

3. 사용자 업데이트

http://myweb/users 라는 사용자 리소스중에, id가 terry 인 사용자 정보에 대해서, 주소를 “suwon”으로 수정(업데이트)

HTTP PUT, http://myweb/users/terry
{
    "name":"terry",
    "address":"suwon"
}

4. 사용자 삭제

http://myweb/users 라는 사용자 리소스중에, id가 terry인 사용자 정보를 삭제

HTTP DELETE, http://myweb/users/terry

단순하게 리소스를 URI로 정해준 후에, 거기에 HTTP 메서드를 이용해서 CRUD를 구현하고 메시지를 JSON으로 표현하여 HTTP Body에 실어 보내면 된다. POST URI에 리소스 id가 없다는 것을 빼면 크게 신경쓸 부분이 없다.

REST의 특성

유니폼 인터페이스(Uniform Interface)

• REST는 HTTP 표준에만 따른 다면, 어떠한 기술이라던지 사용이 가능한 인터페이스 스타일이다. 예를 들어 HTTP + JSON으로 REST API를 정의했다면, 안드로이드 플랫폼이건, iOS 플랫폼이건, 또는 C나 Java/Python이건 특정 언어나 기술에 종속 받지 않고 HTTP와 JSON을 사용할 수 있는 모든 플랫폼에 사용이 가능한 느슨한 결함(Loosely coupling) 형태의 구조이다.

• ※ 흔히들 근래에 REST를 이야기 하면, HTTP + JSON을 쉽게 떠올리는데, JSON은 하나의 옵션일뿐, 메시지 포맷을 꼭 JSON으로 적용해야할 필요는 없다. 자바스크립트가 유행하기전에만 해도 XML 형태를 많이 사용했으며, 근래에 들어서 사용의 편리성 때문에 JSON을 많이 사용하고 있지만, XML을 사용할 경우, XPath,XSL등 다양한 XML 프레임웍을 사용할 수 있을뿐만 아니라 메시지 구조를 명시적으로 정의할 수 있는 XML Scheme나 DTD등을 사용할 수 있기 때문에, 복잡도는 올라가더라도, 메시지 정의의 명확성을 더할 수 있다.

무상태성/스테이트리스(Stateless)

• REST는 REpresentational State Transfer 의 약어로 Stateless (상태 유지하지 않음)이 특징 중의 하나이다. 상태가 있다 없다는 의미는 사용자나 클라이언트의 컨택스트를 서버쪽에 유지 하지 않는다는 의미로,쉽게 표현하면 HTTP Session과 같은 컨텍스트 저장소에 상태 정보를 저장하지 않는 형태를 의미한다. 상태 정보를 저장하지 않으면 각 API 서버는 들어오는 요청만을 들어오는 메시지로만 처리하면 되며, 세션과 같은 컨텍스트 정보를 신경쓸 필요가 없기 때문에 구현이 단순해진다.

캐슁 가능(Cacheable)

REST의 큰 특징 중의 하나는 HTTP라는 기존의 웹 표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존의 인프라를 그대로 활용이 가능하다. HTTP 프로토콜 기반의 로드 밸런서나 SSL은 물론이고, HTTP가 가진 가장 강력한 특징중의 하나인 캐슁 기능을 적용할 수 있다.일반적인 서비스 시스템에서 60%에서 많게는 80%가량의 트렌젝션이 Select와 같은 조회성 트렌젝션인 것을 감안하면, HTTP의 리소스들을 웹캐쉬 서버등에 캐슁하는 것은 용량이나 성능 면에서 많은 장점을 가지고 올 수 있다.구현은 HTTP 프로토콜 표준에서 사용하는 “Last-Modified” 태그나 E-Tag를 이용하면 캐슁을 구현할 수 있다. 아래와 같이 Client가 HTTP GET을 “Last-Modified” 값과 함께 보냈을 때, 컨텐츠가 변화가 없으면 REST 컴포넌트는 “304 Not Modified”를 리턴하면 Client는 자체 캐쉬에 저장된 값을 사용하게 된다.

이렇게 캐쉬를 사용하게 되면 네트웍 응답시간 뿐만 아니라, REST 컴포넌트가 위치한 서버에 트렌젝션을 발생시키지 않기 때문에, 전체 응답시간과 성능 그리고 서버의 자원 사용률을 비약적으로 향상 시킬 수 있다.

자체 표현 구조(Self-descriptiveness)

• REST의 가장 큰 특징 중의 하나는 REST API 자체가 매우 쉬워서 API 메시지 자체만 보고도 API를 이해할 수 있는 Self-descriptiveness 구조를 갖는 다는 것이다. 리소스와 메서드를 이용해서 어떤 메서드에 무슨 행위를 하는지를 알 수 있으며, 또한 메시지 포맷 역시 JSON을 이용해서 직관적으로 이해가 가능한 구조이다. 대부분의 REST 기반의 OPEN API들이 API 문서를 별도로 제공하고 있지만, 디자인 사상은 최소한의 문서의 도움만으로도 API 자체를 이해할 수 있어야 한다.

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

근래에 들면서 재 정립되고 있는 특징 중의 하나는 REST가 클라이언트 서버 구조라는 것이다.

• REST 서버는 API를 제공하고, 제공된 API를 이용해서 비즈니스 로직 처리 및 저장을 책임진다.
• 클라이언트의 경우 사용자 인증이나 컨택스트(세션,로그인 정보)등을 직접 관리하고 책임 지는 구조로 역할이 나뉘어 지고 있다.

이렇게 역할이 각각 확실하게 구분되면서, 개발 관점에서 클라이언트와 서버에서 개발해야 할 내용들이 명확하게 되고 서로의 개발에 있어서 의존성이 줄어들게 된다.

계층형 구조 (Layered System)

계층형 아키텍쳐 구조 역시 근래에 들어서 주목받기 시작한 구조

• 클라이언트 입장에서는 REST API 서버만 호출한다.
• 서버는 다중 계층으로 구성될 수 있다. 순수 비즈니스 로직을 수행하는 API 서버와 그 앞단에 사용자 인증 (Authentication), 암호화 (SSL), 로드밸런싱등을 하는 계층을 추가해서 구조상의 유연성을 둘 수 있는데, 이는 근래에 들어서 앞에서 언급한 마이크로 서비스 아키텍쳐의 api gateway나, 간단한 기능의 경우에는 HA Proxy나 Apache와 같은 Reverse Proxy를 이용해서 구현하는 경우가 많다.

REST 안티 패턴 (개발시 주의사항)

REST 디자인시 하지 말아야 할 안티 패턴

GET/POST를 이용한 터널링

가장 나쁜 디자인 중 하나가 GET이나 POST를 이용한 터널링이다.
http://myweb/users?method=update&id=terry 이 경우가 전형적인 GET을 이용한 터널링이다. 메서드의 실제 동작은 리소스를 업데이트 하는 내용인데, HTTP PUT을 사용하지 않고, GET에 쿼리 패러미터로 method=update라고 넘겨서, 이 메서드가 수정 메세드임을 명시했다.
대단히 안좋은 디자인인데, HTTP 메서드 사상을 따르지 않았기 때문에, REST라고 부를 수 도 없고, 또한 웹 캐쉬 인프라등도 사용이 불가능하다.
또 많이 사용하는 안좋은예는 POST를 이용한 터널링이다. Insert(Create)성 오퍼러이션이 아닌데도 불구하고, JSON 바디에 오퍼레이션 명을 넘기는 형태인데 예를 들어 특정 사용자 정보를 가지고 오는 API를 아래와 같이 POST를 이용해서 만든 경우이다.

HTTP POST, http://myweb/users/
{  
    "getuser":{  
               "id":"terry"
              }
}

Self-descriptiveness 속성을 사용하지 않음

앞서 특징에서 설명한 바와 같이 REST의 특성중 하나는 자기 서술성(Self-descriptiveness) 속성으로 REST URI와 메서드 그리고 쉽게 정의된 메시지 포맷에 의해서 쉽게 API를 이해할 수 있는 기능이 되어야 한다. 특히나 자기 서술성을 깨먹는 가장 대표적인 사례가 앞서 언급한 GET이나 POST를 이용한 터널링을 이용한 구조가 된다.

HTTP Response code를 사용하지 않음

다음으로 많이 하는 실수중의 하나가 Http Response code를 충실하게 따르지 않고, 성공은 200, 실패는 500 과 같이 1~2개의 HTTP response code만 사용하는 경우이다. 심한 경우에는 에러도 HTTP Response code 200으로 정의한후 별도의 에러 메시지를 200 response code와 함께 보내는 경우인데, 이는 REST 디자인 사상에도 어긋남은 물론이고 자기 서술성에도 어긋난다.

RESTful web API(RESTful web service)

• REST 아키텍쳐 스타일에 따라 정의되고 이용되는 서비스나 응용을 RESTful 웹 서비스라고함
• OpenAPI 형태의 서비스 제공에 많이 사용됨

HTTP 메서드

• REST에서는 행위에 대한 메서드를 HTTP 메서드를 그대로 사용함
• HTTP에는 여러가지 메서드가 있지만 REST 에서는 CRUD(Create Read Update Delete)에 해당하는 4가지의 메서드만 사용
• POST - Create, GET - SELECT, PUT - UPDATE, DELETE - DELETE

Reference

요즘 많은 것을 참고 하고 있는 조대협님 블로그
http://bcho.tistory.com/

[출처] REST API란|작성자 디딤돌 fit