[RESTful API 설계하기] 2. RESTful API 특징

[RESTful API] 1. RESTful과 API

[RESTful API 설계하기] 3. RESTful API 데이터 조회 GET Method

[RESTful API 설계하기] 4. RESTful API 데이터 생성 POST Method

RESTful API는 HTTP Methods를 이용하여 데이터를 조작할 수 있는 도구다.
RESTful 하다는 것은 대표적으로 GET, POST, PUT(PATCH), DELETE, OPTIONS, HEAD를 이용하여 데이터를 조작하는 것인데, 이는 다음 글에서 얘기하도록 하고 오늘은 RESTful 하다는 것은 어떤 가이드 라인을 지켜야 하는지 얘기하려 한다. 물론 아직 나도 RESTful을 완전히 구현할 수 없기 때문에, 이 글을 읽는 독자께서 내가 설명하고자 하는 것에 의문이나 현실과 괴리감을 느낄 수 있다. 그럴 경우 알려주시면 감사하겠다.

---

우선, REpresentational State Transfer이라는 이름과 같이 '상태를 표현하는' 아키텍처가 RESTful API다.
상태를 표현하기 위해 많은 방법이 있겠지만, 그중 RESTful API는 HTTP 프로토콜을 이용한다. 즉, URI를 이용해 얻고자 하는 대상에 대한 상태를 획득할 수 있다.
HTTP를 이용하기 때문에, 우리가 얻는 특징은 다음과 같다.

1. 캐싱 : HTTP자체의 Last-Modified 등 태그를 이용하여 캐싱을 할 수 있으며, 필요시 기능 구현을 위한 내용을 서버에 미리 정의해 놓을 수 있다.
2. 무상태성 : HTTP 프로토콜은 요청에 대한 응답을 통한 통신이기 때문에, REST API는 응답 전/후에 아무 상태를 갖지 않는다.
3. 계층형 구조 : HTTP 프로토콜 이외의 계층을 API 요청 처리를 위한 객체(혹은 동작) 안에 정의하여 보안, 유저인증, 암호화 등을 Flexible하게 추가할 수 있다. 클라이언트는 RESTful API 서버에 단지 '요청'을 보내고, 이 안의 동작을 알 필요가 없기 때문에 이런 설계가 가능하다.

1. 캐싱

캐싱은 간단하다. 우리가 흔히 알고있는 그 캐싱을 의미하며, 같은 URI에 대해 조회 요청이 발생했을 때, 일전에 가지고 있는 데이터로 응답하기 위한 기능이다.
서버 어딘가에 캐싱을 위한 객체를 만들어 놓고, lifetime, 새로운 생성 요청 등 특정 트리거가 발동되면 캐싱된 데이터를 무시하고, 새로운 조회를 한 뒤에 해당 결과를 캐싱하면 된다.

2. 무상태성

무상태성은 그냥 말 그대로 HTTP는 아무 상태를 갖지 않기 때문에 발생하는 특징이다.

3. 계층형 구조

계층형 구조는 HTTP 요청이 클라이언트 <--> 서버간 발생하는 통신이고, 클라이언트는 서버가 어떻게 동작하는지 알 필요 없이 요청을 보내고, 서버는 내부의 동작을 통해 응답을 생성하여 보내면 된다.
따라서 서버는 내부에 계층을 추가할 수 있고, 이로 인해 계층형 구조(Layered Structure)라는 특징을 갖는다.
쉽게 말해 User Authenticate Layer, Cryptography Layer, Secure Layer 등 원하는 것을 서버에 구성해 놓고, 사용자는 단지 여기에 유저 토큰, 공개키, HTTPS 통신 등 알맞은 요청을 보내면 된다.

---

이와 별개로, HTTP를 이용하기 때문에 주의해야 할 특징들도 있다.

첫 째, URI에 목적을 명시해서는 안된다.

RESTful API는 보통 데이터의 관리를 위한 내용 제공이 대부분이고, 따라서 데이터 조회, 수정, 삭제 등 관련 내용을 수행함에 따라 직관적으로 알기 위해 다음과 같이 설계하는 경우가 있다.

http://myrest.api/user/get/name
(앞으로는 URI부분만 작성하겠다.)

즉 이처럼 uri 자체에 데이터 조작과 관련된 목적의 행위를 기술하지 않아야 한다. 데이터 조작과 관련된 행위는 모두 HTTP 6 Methods에 정의되어 있다.
즉, 위 요청은 다음과 같이 변환되어야 한다.

GET /user/name

둘 째, URI Segment를 활용하여 대상을 한정한다.
그리고 Query String을 활용해 기능을 할당해라.

Query String을 활용하여 RESTful API에 대한 접근을 하는 경우도 많지만, 만들때는 편하더라도 꽤 불편할 수 있다.
이 두번 째 내용은 내가 MkWeb에서 RESTful API를 설계하며 얻은 팁이다.
Query String은 보통 URI 제일 마지막 세그먼트 이후에 붙는 녀석인데, 다음과 같이 생겼다.

GET /user?id=짧은머리%20개발자&age=~...

RESTful API에 대해 어느정도 이해한 사람은 위 구문이 Query String을 통해 대상을 한정한 구문이다. 하지만 우리가 데이터를 검색할 때는 많은 제약조건이나 요구사항에 마주할 수 있다.
예를 들어, 검색 내용에 대해 정렬시키거나, 모두 소문자 혹은 대문자로 바꾸거나, 한 페이지에 불러올 개수를 바꾸는 등. 우리가 딱딱한 RESTful API를 설계하게 되면, 이는 수정할 수 없게된다.
혹은 대상 한정자와 추가 기능에 대해 모두 Query String으로 해버리면, 사용할 때 꽤나 까다로울 수 있다.
따라서 다음과 같이 정의하는 것이 좋다.

GET /user/id/짧은머리 개발자/age/13?order=desc&lowercase&numOfRows=20

파란색은 대상 한정자, 보라색은 추가 기능이다.

셋 째, 데이터 대상에 대한 내용이 아닌 이상 소문자를 사용하고,
확장자는 표시하지 마라.

소문자는 일관된 사용성을 위해 추천하는 바고, 확장자는 보안을 위해, 그리고 조금 더 유연한 자원 활용을 위해 표시하지 마라.

---

이러한 특징을 잘 지켜서 작성하면 RESTful API라 칭할 수 있다. 그렇다고, 캐싱을 안했다 해서 RESTful API가 아닌 것은 아니다.
특징들은 모두 '설계를 위한 가이드라인'이지, '설계를 위한 매뉴얼' 같은 것이 아니다. 그렇다 해서 딱 하나만 지키고 RESTful API라 하는 사람은 없을거라 믿는다.