[CS] REST API 개요

✨  REST API  개요 

REST API 는 Representational State Transfer API 의 약자이다. REST 와 API 는 따로 구분해서 생각하면 좋은데, REST 는 하나의 아키텍쳐 (방법론) 에 가깝다. 그렇기 때문에 몇 가지 주요 원칙들이 존재하며, 이를 잘 지킨 API 를 "RESTful" 하다고 표현한다. API 는 Application Programming Interface 의 약자로, 서버가 클라이언트에게 제공하는 리소스 활용 방법이 담긴 인터페이스이다. 

 

📍  API 

API 를 처음 들으면 서버, DB 의 개념과 헷갈릴 수 있다. 하지만 API 는 서버도 DB 도 아니다. 서버와 DB 가 제공하는 데이터 또는 기능에 접근할 수 있도록 해주는 안내판에 가깝다. 가령, vodkamitlime.com 의 서버에서 sayHello() 라는 함수를 준비해놓았다고 하자. 서버는 외부에서 이 함수를 호출하면 언제든지 "hello world!" 를 출력하여 반환할 준비가 되어 있다. 하지만 API 가 없다면 그 누구도 이 함수를 호출하는 방법을 모를 것이다. vodkamitlime.com/test 에 접속해야하는지, vodkamitlime.com?order=true 로 접속해야 하는지 등의 정보가 없다면 서버에서 원하는 리소스를 얻어올 수 없다. 

 

이처럼 외부에서 서버의 자원을 적절히 불러올 수 있도록 활용 방법을 구성한 것이 API 다. 

 

웹 API가 점차 확산되며 이를 표준화하기 위한 프로토콜인 SOAP(Simple Object Access Protocol)이 개발되었다. SOAP API는 XML을 사용하며 HTTP, SMTP, TCP 등의 요청을 주고받았으며, 간편한 방법으로 애플리케이션을 다양한 환경에서 실행할 수 있었다. 

 

POST http://www.stgregorioschurchdc.org/cgi/websvccal.cgi HTTP/1.1 
Accept-Encoding: gzip,deflate 
Content-Type: text/xml;charset=UTF-8 
SOAPAction: "http://www.stgregorioschurchdc.org/Calendar#easter_date" 
Content-Length: 479 
Host: www.stgregorioschurchdc.org 
Connection: Keep-Alive 
User-Agent: Apache-HttpClient/4.1.1 (java 1.5) 
<?xml version="1.0"?> 
<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:cal="http://www.stgregorioschurchdc.org/Calendar"> 
<soapenv:Header/> 
<soapenv:Body> 
   <cal:easter_date soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> 
   <year xsi:type="xsd:short">2014</year> 
</cal:easter_date> 
</soapenv:Body> 
</soapenv:Envelope>

 

위의 예시는 SOAP API 로 보낸 요청의 예시다. 보이다시피 XML 로 요청을 주고받을 경우 payload 의 양이 굉장히 크기 때문에 네트워크 대역폭을 많이 차지하는 문제가 생겨, 인터넷 통신이 기하급수적으로 늘어난 21세기 통신에는 어울리지 않았다. 이러한 문제점을 해결하면서 동시에 인터넷 통신을 편리하게 하고자 했던 것이 바로 2000년에 등장한 REST 아키텍쳐 API 인 것이다. 

 

✨  구성 요소 

REST API 는 자원, 행위, 표현으로 구성되며, 자체 표현 구조 (Self-descriptiveness) 로 구성되어 API 만으로도 HTTP 의 요청을 직관적으로 이해할 수 있다. 

 

📍  자원(Resource) : URI

자원은 서버에 저장되어 있으며, 해당 자원에 접근할 수 있는 URI 가 존재한다. 클라이언트는 URI 를 통해 해당 자원을 조작하고, CRUD 작업을 수행할 수 있다. 

 

📍  행위(Verb) : HTTP Method

자원에 대한 행위이다. POST, GET, PUT, DELETE 와 같은 HTTP 요청 메서드를 의미한다.

 

📍  표현(Representation of Resource)

행위의 구체적인 내용이다. 

 

 

✨  주요 원칙

어떠한 API가 RESTful 하기 위해서는 다음 두 가지 전제를 충족해야 한다. 

 

1) URI 는 리소스를 표현해야 한다.

2) 리소스에 대한 행위는 HTTP 요청 메서드로 표현한다. 

 

이 두 가지를 하나씩 구체적으로 살펴보자. 

 

📍 1) URI 는 리소스를 표현해야 한다.

"리소스를 표현해야 한다"는 말의 의미는 "행위를 통해 조작되는 자원을 상징하는 단어를 표기해야 한다" 에 가깝다. 사실 이 원칙은 부정문으로 표현하는 것이 더 적합할 듯 싶기도 한다. 달리 말하면, "URI 는 행위를 표현하면 안된다" 에 가깝다. 사람이라면 보통 action 위주로 생각하기 마련이다. 때문에 "이 uri 에 접속하면 게시물 삭제가 될 것이다" 는 생각이 URI 에 노출되는 경우가 생긴다.

 

ex ) vodkamitlime.com/delete/boardPost/1

 

하지만 이는 REST 에서는 권장하지 않는 방법이다. URI 에 행위가 직접적으로 노출되고, 어떤 자원이 전달되는지 직관적으로 파악하기 힘들기 때문이다.

 

📍 2) 리소스에 대한 행위는 HTTP 요청 메서드로 표현한다.

 

두번째 원칙은 HTTP 메서드와 직결된 내용이다. 주요한 HTTP 요청 메서드는 크게 5가지가 있으며, 각각의 역할은 다음과 같다.

 

GET: 리소스 취득

POST: 리소스 생성

PUT: 리소스 전체 교체

PATCH: 리소스 일부 수정 

DELETE: 리소스 삭제 

 

HTTP 메서드는 리소스 (자원) 에 대해 수행할 수 있는 행위의 종류이다. 따라서 역시나 URI 에 직접 노출되어서는 안된다. 앞서 게시물을 삭제하는 URI 로는 다음 케이스가 더 적절하다. 행위를 직접 노출하지도 않고 서버가 처리하는 리소스 (자원) 을 정확히 명시하기 때문이다.

DELETE     vodkamitlime.com/boardPost/1

 

 

📌  기타 원칙 

REST API 를 구성하는 소소한 몇 가지 추가 원칙이 있으며, 이는 다음과 같다. 

 

- 요청과 응답 payload 는 JSON 으로 주고받는다. 

-  /  로 구분된 path 를 통해 계층관계를 나타낸다.

- 응답을 보낼 때 적절한 HTTP 상태 코드를 보낸다. 

- Spinal-case 를 권장한다.

- HTTP 헤더에 요청과 응답에 대한 주요 정보를 담는다. (General/Request/Response Headers)

- resource 는 소문자, 단수 명사 사용을 지향한다.

- 파일확장자는 포함하지 않는다.

 

 

✨  참고 자료

• API(애플리케이션 프로그래밍 인터페이스)란 - 개념, 기능, 장점
• 모던 자바스크립트 Deep Dive (위키북스) 
• What is a REST API?
• [Network] REST란? REST API란? RESTful이란?