말하고 싶은 것

REST란 무엇인가?
RESTful하다는 것은 무엇을 의미하며, 어떻게 해야하는가?

REST

REST는 REpresentation State Transfer의 약자로, WWW(World Wide Web) 같은 분산 하이퍼미디어 시스템에서 운영되는 소프트웨어 아키텍처 스타일입니다.

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

REST는 HTTP/1.1 스펙과 동시에 만들어졌는데, HTTP 프로토콜을 정확히 의도에 맞게 활용하여 디자인하게 유도하고 있기 때문에 디자인 기준이 명확해지며, 의미적인 범용성을 지니므로 중간 계층의 컴포넌트들이 서비스를 최적화하는 데 도움이 됩니다.

REST의 기본 원칙을 성실히 지킨 서비스 디자인은 “RESTful 하다” 라고 흔히 표현합니다.

REST의 6가지 원칙(제약 사항)

1. Uniform Interface

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

REST의 또 다른 큰 특징 중 하나는 REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조(Self-descriptiveness)로 되어 있다는 것입니다.

2. Stateless

REST는 무상태성 성격을 갖습니다. 다시 말해 작업을 위한 상태정보를 따로 저장하고 관리하지 않습니다. 세션 정보나 쿠키정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만을 단순히 처리하면 됩니다.

때문에 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해집니다.

3. Cacheable

REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용이 가능합니다. 따라서 HTTP가 가진 캐싱 기능이 적용 가능합니다. HTTP 프로토콜 표준에서 사용하는 Last-Modified태그나 E-Tag를 이용하면 캐싱 구현이 가능합니다.

4. Client - Server 구조

REST 서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보)등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로간 의존성이 줄어들게 됩니다.

5. Hierarchical System(Layered System)

REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 합니다.

6. Code-on-Demend(optional)

서버가 네트워크를 통해 클라이언트에 프로그램을 전달하면 그 프로그램이 클라이언트에서 실행될 수 있어야합니다. (Java applet이나 Javascript 같은 것을 말함) 다만 이 제약조건은 필수는 아닙니다.

REST API

위 REST의 원칙에 따라 디자인한 API를 REST API라고 합니다.

REST API의 구성

REST API는 자원(Resource), 행위(Verb), 표현(Representations)의 3가지 요소로 구성됩니다. REST는 자체 표현 구조(Self-descriptiveness)로 구성되어 REST API만으로 요청을 이해할 수 있습니다.

구성 요소	내용	표현방법
Resouce	자원	HTTP URI
Verb	자원에 대한 행위	HTTP method
Representations	자원에 대한 행위의 내용	HTTP Message Pay Load

REST API 설계 시, 주의할 점

자원에 대한 행위는 HTTP Method으로 표현한다.

URI는 정보의 자원을 표현해야 해야합니다. 또한 그 자원에 대한 행위는 HTTP Method(GET, PUT, POST, DELETE)로 표현합니다. 대부분의 행위는 HTTP Method만으로 표현이 가능하기 때문에, URI에 CRUD를 사용하지 않도록 합니다.

예를들어 임의의 회원(사용자)에 대한 정보를 삭제하는 API를 작성할 때,

DELETE /members/delete/1

위와 같은 방식은 REST를 제대로 적용하지 않은 URI입니다. URI는 자원을 표현하는데 중점을 두어야 합니다. delete와 같은 행위에 대한 표현이 들어가서는 안됩니다.

위에서 설명한 두 가지를 적용한다면, 다음과 같이 수정할 수 있습니다.

DELETE /members/1

그 이외에는,

회원정보 조회

GET /members/show/1     (Not RESTful)
GET /members/1          (RESTful)

회원 추가

POST /members/insert/2  (NOT RESTful)
POST /members/2         (RESTful)

위와 같이 작성할 수 있습니다.

HTTP Method

자원은 크게 Collection과 Element로 나누어 표현할 수 있으며, 아래 테이블에 기초한다면 서버 대부분과의 통신 행태를 표현할 수 있습니다.

	Collection URI, ex) `/memeber/`	Element URI, ex) `/member/:id`
GET	컬렉션에 속한 자원들의 URI나 그 상세사항의 목록을 보여준다.	요청한 컬렉션 내 자원을 반환한다.
PUT	전체 컬렉션은 다른 컬렉션으로 교체한다.	해당 자원을 수정한다.
POST	해당 컬렉션에 속하는 새로운 자원을 생성한다. 자원의 URI는 시스템에 의해 할당된다.	해당 자원에 귀속되는 새로운 자원을 생성한다.
DELETE	전체 컬렉션을 삭제한다.	해당 컬렉션내 자원을 삭제한다.

Collection과 Document

Resouce는 Collection과 Document로 구분할 수 있습니다. Document는 Element라고도 표현하며, 하나의 Resouce 개체, 또는 문서를 말합니다. 그러한 Document의 집합을 Collection이라고 할 수 있습니다.

예를들어,

http://delf.com/sport/soccer

다음 URI는 sports라는 Collection과 soccer라는 Document로 표현되고 있습니다. sports Collection에는 soccer이외에 baseball이나 basketball등이 포함될 수 있습니다.

좀 더 예를 들어보자면,

http://delf.com/sports/soccer/players/13

sports, players 컬렉션과 soccer, 13(13번인 선수)를 의미하는 도큐먼트로 URI가 이루어지게 됩니다. 여기서 중요한 점은 컬렉션은 복수로 사용하고 있다는 점입니다. 좀 더 직관적인 REST API를 위해서는 컬렉션과 도큐먼트를 사용할 때 단수 복수도 지켜준다면 좀 더 이해하기 쉬운 URI를 설계할 수 있습니다.

소문자를 사용한다.

대문자를 사용해도 상관이 없지만, 대문자와 소문자가 구분된다는 사실은 알고있어야 합니다. 다음 URI는 모두 다른 리소스 입니다.

http://delf.com/RESTfulAPI
http://delf.com/RESTfulapi
http://delf.com/restfulAPI

공백과 언더바(_)보다는 하이픈(-)을 사용한다.

언더바(_)를 사용하면 밑줄에 겹쳐서 보이지 않게 되거나 공백을 사용하면 %20과 같이 인코딩되어 가독성이 떨어지게 됩니다. 사용이 불가능한 것은 아니지만 되도록 하이픈(-) 사용을 권장합니다.

http://delf.com/what-is-rest-api

자원에 대한 확장자를 명시하지 않는다.

URI에 확장자를 표시하기 보다는 Accept header를 이용합니다.

http://delf.com/cat.txt

위의 URI를 REST API로 구현한다면 다음과 같아집니다.

GET /cat HTTP/1.1
Host: delf.com
Accept: text/plain

또는, 다음같이 다른 형대로 요청할 수 있습니다.

GET /cat HTTP/1.1           
Host: delf.com
Accept: text/csv

이로써, 하나의 Resource에 대해서 하나의 URI에 대응할 수 있게되고, 클라이언트의 요청에 대한 응답을 좀더 유연하게 할 수 있습니다.

RESTful과 REST API