[REST 설계] REST API 소개

REST API 란 뭘까?

---

 

REST API 소개

 REST API 는 웹확장성이 고려된 웹 구조적 아키텍쳐 스타일에서 2000년대 초반 Representational State Transfer 의 약자로서 소개 되었다. 이는 아파치 HTTP 서버 프로젝트를 주도한 로이 필딩 박사의 웹의 구조적 확장성에 대한 고민의 부산물이다.

 웹 서비스는 특정한 목적을 위해 만들어진 웹 서버로, 다른 사이트나 다른 어플리케이션이 필요로 하는 것을 제공하하는데, 보통 클라이언트 프로그램은 웹 서버에서 제공하는 API를 이용하여 웹서비스와 통신한다. 오늘날 web application server 라고 불리는 WAS 에서 제공하는 API (application programming Interface) 라고 이해하면 쉽다.

 API는 데이터와 기능의 집합을 제공하고 컴퓨터 프로그램 간 상호작용을 촉진하며 서로의 정보를 교환 할 수 있게 해준다. 결국 API란 웹서비스 와 클라이언트의 최접점에서 클라이언트의 요청을 직접적으로 요청하고 응답하는 역할을 하는 것이다.

 

 REST 아키텍쳐 스타일은 하드웨어적 컴퓨팅 기술과 네트워크 기술의 영역 확장으로 인해 뺄래야 뺄 수 없는 필수 패턴이 되었으며 RESTful API는 이제 MSA , DDD 등의 엔진 분산형 아키텍쳐에 없어서는 안될 주요 통신채널로서의 역할을 수행 한다.

 그만큼 REST 아키텍쳐 스타일은 최근 (사실 최근이라고 하기에도 민망할 정도로 이미 과거부터 지배적인 포지션...)부쩍 웹 서비스를 위한 API 설계에 많이 적용 되고 있으며, 이 REST 아키텍쳐 스타일에 적합한 web API를 REST API라고 한다.

---

 

REST의 구성과 특징

REST는 다음의 구성으로 이루어져 있다.

(본 포스팅은 REST API의 설계 패턴에 대한 규칙을 답습하기 위함이 목적이므로 개념적인 상세한 설명은 생략한다)

• 자원 (resource)
  • URI 라는 리소스를 나타내는 식별자로 대표 된다.
• 행위 (Verb)
  • HTTP method 를 의미하며 GET, POST, PUT, DELETE 로 표현 된다.
• 표현 (Representations)
  • 컴포넌트 간에 이동하는 메시지를 통해 전송 될 수 있는 자원의 형식화 된 포맷이다.

REST는 다음의 특징을 가진다.

 

1) Client - Server 구조

 웹은 클라이언트/서버 기반 시스템으로 클라이언트/서버 규약의 핵심은 관심사의 분리다. 이는 시스템 내에서 클라이언트와 서버의 명확한 역할 분리를 의미하며 클라이언트와 서버는 각자의 언어 및 기술을 사용하여 독립적으로 구현되고 배포된다. 즉, 서버는 REST API제공, 클라이언트는 사용자 인증이나 컨텍스트 등을 직접 관리 하는 구조로 각각의 역할이 확실히 구분되며 서로간의 의존성을 줄인다.

 

2) Uniform Interface

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

 

3) Stateless

 웹서버는 웹 어플리케이션과의 복잡한 인터페이스를 위해 필요한 상태관리를 클라이언트에 맡김으로써 더 많은 클라이언트에 서비스 할 수 있다. 비록 클라이언트는 웹 서버와의 상호작용에서 발생하는 각종 상황 정보를 직접 관리 해야하므로 트레이드 오프가 생기지만 이러한 관점은 웹 의 아키텍쳐 스타일의 확장성에 이바지 한다. 서비스의 자유도는 높아지고 서버에서는 불필요한 정보를 관리 하지 않음으로써 구현이 단순해진다.

 

4) Cache

 REST는 HTTP라는 기존 웹 표준을 그대로 활용 하므로 HTTP가 가징 캐싱 기능을 그대로 활용 할 수 있다. 즉, HTTP 프로토콜 표준에서 사용하는 last-modified나 E-tag를 이용해서 캐시를 구현할 수 있다. 캐시 응답 데이터는 클라이언트가 느끼는 지연을 감소시키고 어플리케이션의 전체적인 이용 가능성과 안정성을 향상 시키며, 웹서버의 부하를 제어한다.

 

 5) Self descriptiveness

 자체 표현 구조다. REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조로 되어있다.

 

 6) 계층 시스템

 REST 서버는 다중 계층으로 구성 될 수 있으며 보안, 로드밸런싱, 암호화 계층을 추가하여 구조적 유연성을 가져갈 수 있다. proxy, gateway 와 같은 네트워크 기반의 중간매체를 활용 함으로서 웹의 일관된 인터페이스를 사용 한다면 중간 매체를 클라이언트와 서버 사이에 마치 없는 것처럼 배치 할 수 있다.

---

 

REST를 잘 설계 한다는 것

 REST API를 제공하는 웹 서비스를 RESTful 하다고 하는데, REST API는 상호 연결된 리소스의 결합체이며, 이 리소스 집합을 일컬어 REST API의 리소스 모델이라고 한다.

 잘 설계 된 REST API는 웹서비스를 사용할 클라이언트들에게 효과적인 통신 방법 표준을 제시하며, 만약 잘 설계 되지 않은 패턴으로 배포된 API가 있다면 이것을 다시 회수하고 수정 하는데 많은 노력과 시간이 든다.

REST API 설계의 몇가지 모범 사례는 HTTP 표준에 포함 되어 있지만, 실제 시스템을 설계 하고 개발함에 있어서 여전히 아래의 주요 질문들은 고민 사항이다.

• URI path의 각 segment 네이밍에는 언제 복수를 써야 하는가?
• 리소스의 상태를 업데이트 하려면, 어떤 메서드를 써야 하는가?
• CRUD가 아닌 연산을 어덯게 url 에 매핑하는가?
• 특정한 시나리오에 가장 적합한 HTTP 응답은 무엇인가?
• 리소스 상태 표현의 버전은 어떻게 관리할 수 있는가?
• JSON에 포함된 하이퍼링크는 어떻게 구조화 하는가?
• 기타 등등..?

 이 포스팅 시리즈는 Marke Masse 저서인 O’REILLY 의 REST API Design Rulebook 의 번역서를 학습하고 얻은 지식을 정리한 결과물이다.

 책에서 제안하는 규칙은 현업에서 실제 엔지니어링 수행 시 REST API를 일관된 방식으로 설계하는데 큰 도움을 주고, 클라이언트에서 API의 효율적 활용을 촉진 할 것으로 기대 된다.

 궁극적으로는 이 포스팅 시리즈를 통해 위에 나열한 것과 같은 질문에 대한 해답과, 실제 내가 현업에서 시스템을 설계/개발 할때 좀 더 표준화 되고 합리적인 설계를 해 나가기 위함을 목표로 한다.

 

 

---

시리즈 포스팅의 시작글으로 간략히 REST의 개념과 특징에 대해 간략히 소개 하였다.

다음 글에서는 REST API에서 리소스를 나타날때 쓰이는 가장 중요한 식별자인 URI 식별자 설계를 다룰 예정이다.