개발을 하다보면 REST API 를 많이 사용하게 되는데 정말 내가 진짜 REST API 를 사용하고 있는가 다시한번 생각해 볼 수 있는 좋은 자료가 있어서 참고하여 나름대로 정리해 보았다.
REST API (Representational State Transfer Application Programming Interface) 란
REST API 는 REST 아키텍쳐를 스타일을 따르는 API로 여기서 REST 란 분산 하이퍼미디어 시스템을 위한 아키텍쳐를 의미한다.
REST는 HTTP 창시자 중 한 명인 로이 필딩(Roy Fielding)의 박사학위 논문에서 최초로 소개된 개념으로 웹과의 호환성을 유지하면서 웹의 장점을 최대한 활용할 수 있는 아키텍쳐를 제시하기 위해 만들어 졌다.
(.. 잘 설계된 웹을 잘 사용하라고 아키텍쳐까지 발표했지만 여전히 어렵다.)
REST의 특징
그렇다면 REST는 어떤 아키텍쳐인가 알기 위해 특징을 살펴보면 다음과 같다.
Client-Server 구조
REST 서버가 API 를 제공하고, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보) 등을 직접 관리하고 책임 지는 구조이다.
Stateless (무상태성)
REST 는 Stateless 즉, 상태를 유지하지 않는 특징을 가지는데 상태를 유지하지 않는 다는 것은 HTTP 세션이나 쿠키 같은 상태 정보를 저장하지 않는 다는 것을 의미한다. REST 서버는 단지 클라이언트의 요청만 처리할 뿐이라 구현이 단순하다.
Cache (캐시)
REST는 HTTP라는 기존 웹 표준을 그대로 사용하기 때문에 HTTP의 캐시 기능을 사용할 수 있다. 애초에 REST가 웹과의 호환성을 고려하여 만들어 졌기 때문에 당연하다고도 볼 수 있다. 예를들어 Last-Modified 태그 등을 사용하여 컨텐츠에 변화가 없으면 클라이언트가 캐싱해놓은 값을 사용하여 서버에 불필요한 트랜젝션 을 발생하지시키지 않아 서버 자원을 효율적으로 사용할 수 있다.
Layered System (계층형 시스템)
REST 서버는 다중 계층으로 구성이 가능하여 HTTP 프로토콜 기반의 로드 밸런서나 SSL (암호화 계층)을 추가할 수 있다.
Uniform Interface (일관성 있는 인터페이스)
REST 는 URI 로 지정한 리소스에 대해 일관성 있는 인터페이스를 제공함으로써 클라이언트와 서버가 독립적인 진화가 가능하다.
진화라는 말이 어색하지만 독립적인 진화라는 말은 쉽게 설명하면 서버가 변경되어도 클라이언트가 따로 업데이트를 할 필요가 없다는 것이다. 예를들어 웹 표준을 잘 지키고 있는 웹 브라우저를 생각하면 된다. 개발자가 서버를 아무리 변경해도 해당 서버에 접속하는 클라이언트는 웹 브라우저를 업데이트할 필요가 없다.
Uniform Interface 의 원칙
로이 필딩은 현재 REST API 라고 주장하는 API 들이 진짜 REST 가 아니며 제대로 REST 의 원칙을 지키거나 HTTP API 와 같은 이름을 사용하라고 말한다.
( .. 자신이 만든 REST 의 원칙을 제대로 안지키면서 REST 라고 떠들고 다니니 답답한 모양이다. )
여기서 로이 필딩이 말하는 REST의 원칙은 Uniform Interface 의 원칙을 의미한다.
Identification of resource (자원의 식별)
말 그대로 자원을 식별할 수 있어야 한다는 원칙인데, 쉽게 생각하면 REST를 구현하기 위해 설계하는 URI 를 생각하면 된다. URI를 통해 자원을 표현하는 것이다.
(.. 많은 개발자들이 URI 를 간단하고 직관적으로 설계하기 위해 고민하는 부분이다. )
Manipulation of resources through representations (표현을 통한 자원의 조작)
클라이언트가 어떤 자원을 가르키는 표현과 특정 메타데이터만 가지고 있다면 서버 상의 해당 자원을 변경 또는 삭제 할 수 있어야 한다는 원칙이다. REST API 를 설계할 때 자원에 대한 표현을 HTTP 메서드인GET,POST,PUT,DELETE 등을 사용하는 부분이라 생각하면 되겠다.
Self-descriptive messages (자기 서술적 메시지)
각 메시지에는 메시지를 어떻게 처리해야 하는지에 대한 충분한 정보를 포함해야한다는 원칙이다.
Uniform Interface 에서 주로 지켜지지 않는 원칙 중 하나로 URI 와 메서드, 메시지 포맷 등으로 REST API 를 쉽게 이해할 수 있어야 한다는 말이다.
예를 들면 HTTP 헤더의 미디어 타입의 정의를 들 수 있다. 미디어 타입의 정의 만으로 해당 메시지를 어떻게 처리해야 하는지 클라이언트가 알 수 있어야 한다.
Hypermedia As The Engine Of Application State(HATEOAS, 애플리케이션 상태에 대한 엔진으로서의 하이퍼미디어 )
이름만 들어도 거창한데 마찬가지로 Uniform Interface 에서 주로 지켜지지 않는 원칙 중 하나로 애플리케이션의 상태가 하이퍼미디어(하이퍼링크)를 통해 제공되어야 한다는 원칙이다.
예를 들어 링크 형태를 이용하면 서버에서 자원에 대한 URI를 변경하더라도 클라이언트에서는 코드 수정이 불필요 하다. 클라이언트는 서버에서 주어진 링크만 따라가면 되므로 서버는 링크를 동적으로 변경할 수 있기 때문이다.
REST API 를 사용해야 할까?
결국 REST API 에서 가장 많이 하는 고민.
개인적인 생각은 "사용하면 좋다" 이다.
다만 REST API 를 제대로 사용하는 것에 대해서는 고민을 해봐야할 것 같다.
REST API의 창시자인 로이 필딩은 다음과 같이 말했다고 한다.
"시스템 전체를 통제할 수 있다고 생각하거나, 진화에 관심이 없다면, REST에 대해 따지느라 시간을 낭비하지 마라."
(.. 명언이다. 실제로 REST 따지느라 시간 낭비를 많이 했었다 )
보통은 URI 나 HTTP 메서드 만 열심히 고민하고 REST API 를 사용했다고 한다.
많은 인싸(?) IT 회사들도 REST API 라고 언급 하지만 위의 원칙들을 다 지키지 않는 경우가 많다.
(.. 시스템 전체를 통제할 수 있는 범위 내에서 적당하게 사용하는 것 같다.)
마이크로소프트는 REST API 가이드라인까지 발표했지만 로이 필딩이 친히 그건 REST API 가 아니라고 까주었다. 중요한건 REST API 는 웹을 잘 활용할 수 있는 아키텍쳐이고, REST 의 원칙들을 자기 상황에 맞게 맞춰 사용하면 된다.
(.. 다만 REST 원칙을 모두 준수하지 않고 REST API 라고 명칭하는건 양심의 문제랄까)
REST API 설계 가이드
REST API 의 특징들은 웹에서 사용하는 기존 인프라를 그대로 활용하는 것들이라 대부분 자동적(?)으로 지켜진다. 그렇기 때문에 특별히 신경써야할 Uniform Interface 의 원칙에 따라 REST API 설계를 간단하게 해보자면 다음과 같다.
1. URI 는 자원을 표현
간단하면서도 직관적으로 만들고 명사를 사용한다.
예) /{colletions}/{id} -> /users/1
2. 표현을 통한 자원의 조작
HTTP 메서드 GET, POST, PUT, DELETE 등을 사용
예) get /users/1 : 아이디가 1 인 유저의 정보를 가져온다.
post /users/2: 아이디가 2인 유저를 추가 한다.
3. 자기 서술적 메시지
미디어 타입을 정의하고나서 IANA에 직접 등록하는 방법과 HTTP Link 헤더에 profile relation 으로 API 문서를 링크하는 방법이 있다.
예) Link : <https://example.com/docs/users>: rel="profile"
4. HATEOAS
HTT 헤더나 응답 데이터에 링크를 넣어 준다.
예) { "name" : "noah" , "links" : [{ "rel" : "self" , "href" : "https://example.com/users/1" }] }
