REST API를 더 REST답게 사용하기

 

 

과거부터 웹의 요청을 처리하는 방법은 웹페이지에서 요청하고 웹서버에서 요청을 처리 후 다시 클라이언트에게 제공하는 하나의 환경으로 제공되었습니다.

 

그러나 현재는 SPA(Single-Page Application)을 지향하는 웹 컴포넌트와 UI 프레임워크 발전 됨에 따라 (Vue.js, React, Angular) 클라이언트를 서버로부터 분리하여 서로 독립적인 관리체계를 가질 수 있게 됐습니다.

 

여기서 서버와 클라이언트를 연결할 때 주로 API(Application Programming Interface) 방식을 사용하고 있으며, 그 중 REST API를 많이 사용하고 있습니다.

 

 

REST API란?

REST(Representational State Transfer)는 소프트웨어 아키텍처 중 하나입니다. 웹 통신 시 HTTP의 장점을 최대로 사용하기 위한 아키텍처로 REST의 핵심은 자주 쓰는 HTTP 메서드에 의미를 부여하여 통신의 상태를 획일화 시키는데 그 의미가 있습니다. 

 

API를 REST 형식으로 제공하면 다음과 같은 이점이 있습니다.

1) 클라이언트 / 서버 분리에 탁월한 구조

클라이언트와 서버를 분리 시 클라이언트는 유저 관련 처리를, 서버는 REST API를 통해 데이터를 제공함으로써 의미 있고 일관된 인터페이스로 서비스를 제공할 수 있습니다.

2) 무상태 (Stateless)

HTTP는 무상태성 프로토콜입니다. REST는 HTTP 특성을 가지고 있어 무상태성을 가질 수 있습니다. 쉽게 말해 요청을 처리하기 위해 상태를 알 필요가 없고, 요청에 따른 독립적인 처리가 가능합니다. 

3) 캐시 처리 가능(Cacheable)

REST는 HTTP의 특성을 가짐과 동시에 웹 표준에 맞는 기능을 사용할 수 있습니다. 덕분에 웹 표준에 근거한 인프라를 그대로 사용 가능합니다. 
로드밸런서, SSL은 물론이며 캐시 기능까지 사용 가능합니다. 캐시 기능을 사용함으로 써 성능적으로 이점을 가질 수 있습니다.

4) 자체 표현 구조(Self-descriptiveness)

REST의 큰 이점이기도 하며 REST API 메시지만으로 의미와 행위를 파악할 수 있어 자체 표현 구조를 가질 수 있습니다. 결과 포맷 또한 흔히 사용하는 JSON, XML 구조를 사용하여 의미를 파악하기 용이합니다. 

오픈 API를 제공하는 입장에서도 최소한의 문서로 제공할 수 있어 큰 이점이 될 수 있습니다.

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

HTTP만 따른다면 어떤 플랫폼이든 가리지 않고 서비스를 제공할 수 있습니다. 즉 서비스 대상과 느슨한 결합(Loosely coupling) 구조를 가지면서 다양한 플랫폼에 동일한 행위와 결과를 제공할 수 있습니다.

6) 계층화(Layered System)

서버와 클라이언트가 분리되어 있어, 중간 매체를 활용하기 용이합니다. 예를 들어 암호화, 인증, 프록시 서버 같은 환경을 도입하기에 필요한 벽이 낮아 자유도가 높습니다.

 

 

REST API를 REST답게 설계 하기

REST API를 잘 설계하기 위해서는 REST의 구성요소를 잘 파악하고 있어야 합니다. 구성요소는 다음과 같습니다.

1) 자원 (Resource)

REST API에서 자원은 흔히 URL을 명명하는 것을 말하며, URL의 명칭은 직관적으로 정해야 합니다.

http://round-round.tistory.com/member/members?memberName=abc
 => 이름이 'abc'인(memberName=abc) 회원들(members)
 
http://round-round.tistory.com/product/hotDeal?category=phone
 => 핸드폰 카테고리의(category=phone) 핫딜 상품(product/hotDeal)

위 예시대로 URL만 보면 직관적으로 어떤 내용인지 예측이 가도록 명명되어야 합니다.

2) 메서드 (Method)

자원에서 URL에 명칭을 직관적으로 정의했다면 HTTP 메서드를 사용해 행위를 정할 수 있습니다. REST 기준으로 메서드는 다음과 같은 행위를 가집니다.

메소드	DML	행위
GET	SELECT	해당 리소스를 조회합니다.
POST	INSERT	해당 리소스를 생성 및 추가 합니다.
PUT	UPDATE	해당 리소스를 수정합니다.
DELETE	DELETE	해당 리소스를 삭제합니다.

4가지 메서드는 DML과 유사한 형태를 띠며, 메서드마다 각각의 행위를 가질 수 있습니다.

GET /member/member?memberName=abc
 => 이름이 'abc'인 회원 조회
POST /member/member?memberName=abc
 => 이름이 'abc'인 회원 추가
PUT /member/member?memberName=abc&newName=bcd
 => 이름이 'abc'인 회원의 이름을 'bcd'로 변경
DELETE /member/member?memberName=abc
 => 이름이 'abc'인 회원 삭제

위 4개의 URL은 서로 같은 값을 가지지만 HTTP의 메서드의 사용에 따라 의미가 서로 달라집니다. 이와 같은 특징 때문에 각 API의 URL과 메서드만 보고도 어떤 기능인지 예측할 수 있습니다.

 

단, HTTP 메서드 외에 URL 자체는 행위를 의미하는 명칭을 가질 수 없습니다.

GET /member/member/get?memberName=abc (x)
 => 이름이 'abc'인 회원 조회
POST /member/push/member?memberName=abc (x)
 => 이름이 'abc'인 회원 추가
PUT /member/updateMember?memberName=abc&newName=bcd (x)
 => 이름이 'abc'인 회원의 이름을 'bcd'로 변경
DELETE /member/delMember?memberName=abc (x)
 => 이름이 'abc'인 회원 삭제

이처럼 행위의 수단이 메서드와 URL로 분리되어 제공될 경우, REST의 이점인 자체 표현 구조(Self-descriptiveness)를 위배하는 행위라 볼 수 있습니다.

3) 메시지(Message)

REST에서 말하는 메시지란 HTTP 응답 코드(HTTP Response code)를 의미합니다. REST는 기본적으로 HTTP의 특성을 가지기 때문에 응답하는 메시지는 HTTP 응답 코드를 지향해야 합니다.

 

 

마치며

REST API는 성능이 중점이 아니라, 사용성에 중점을 둬야 할 거 같습니다. 행위와 의미를 획일화함으로써 오는 장점이 효율적인 인프라 구축과 개발 편의성에 많은 도음이 될 거라 생각합니다.

 

 

참고 자료

https://bcho.tistory.com/953

https://velog.io/@wlsdud2194/HTTP-REST-API-%EB%9E%80

https://ko.wikipedia.org/wiki/REST