[API] RESTful API란?

1. REST API에 대해 

 

1️⃣ REST API란?

REST API란 REST하게 API를 서술하는 방법을 부르는 용어입니다. 여기서 REST 하다는 것은 무슨 의미일까요?

 

REST API = Representational State Transfer API

REST의 약자인 Representational State Transfer은 상태(State)를 전달(Transfer)하는 것을 나타내는(Representational) 방법으로 소개 됩니다. 자원을 이름으로 구분해 해당 자원의 상태(정보)를 주고 받는 것을 의미합니다. 

통신을 한다는 것은 '특정 자원(데이터)을 어떤 방식으로 전달하는 것'으로 간주하고, 이를 표현하는 방식을 통일해 개발자들 사이에서 의사소통을 원활히 하고자 했습니다. 

 

Client의 요청에는 여러 종류가 존재합니다. 

예시: 

• Client가 user(What)정보를 가져오고자(How) 요청하는 것
• Client가 1번(What)의 상품 정보를 가져오고자(How) 요청하는 것
• Client가 2번(What)의 상품을 주문하는 정보를 서버에 주며(How) 주문을 요청하는 것 

예시에서 볼 수 있듯이 요청을 자세히 보면 크게 두 부분으로 나뉘어 있습니다. "무엇을", "어떻게" 입니다. 

"무엇을"에 해당하는 특정 데이터를 resource라고 부르며 URL(Uniform Resource Indentifier)로 표현합니다. "어떻게"는 "어떻게 하겠다"는 동작을 하는 동사이며, http method로 표현합니다. 

 

요청	RESTful API
user들의 정보를 get 하고자 함	[GET] http://localhost:3000/users
상품1의 정보를 get 하고자 함	[GET] http://server.com/products/1
상품2를 주문하고자 함	[POST] http://server.com/order- body{products:2}

 

위의 HTTP GET http://server.com/products/1 요청의 경우 문서나 주석 없이도 "http://servre.com 라는 API에 1번 음료에 관한 정보를 HTTP 요청을 통해 받아오는 거구나" 라는 해석이 쉽게 가능합니다.  

 

2. RESTful API vs SOAP

1️⃣ SOAP 이란?

SOAP(Simple Object Access Protocl)은 XML 기반의 메시지 전송 프로토콜로 REST와는 보안이나 메시지 전송 방식이 다릅니다. 

보편적인 웹 서비스보다 기업 또는 특정 조직 내부에 사용하기에 적합하며 다음과 같은 특징이 있습니다. 

• 원격 프로시저 호출 패턴[ 클라이언트가 로컬에서 실행하는 것 처럼 원격 서버에 위치한 함수 또는 프로시저를 호출하는 패턴 ]
• 플랫폼에 종속되지 않아 이 기종 간 통신 가능
• 헤더와 바디를 가지며 헤더에는 메타 정보, 바디에는 실제 정보가 들어감
• 규약, 에러 처리, 분산 처리에 대한 옵션이 내장

2️⃣ REST 와 SOAP의 차이점

REST와 SOAP은 전세계에 가장 보편화 되어 사용되는 웹 API 패러다임입니다. 두 개념을 학습하면 이해에 도움이 많이 되지만 본질적으로 다른 기술이 아닌 직접적으로 비교하는 것이 적당하지 않습니다. SOAP는 프로토콜이고 REST는 API 설계 스타일이기 때문에, 두 개념을 독립적으로 이해해야 합니다. 

 

🔵 REST 예시 

• 리소스 식별 
  GET /users/123 → ID가 123인 사용자에 대한 정보를 요청하는 것으로 해석됨
• HTTP 메서드 활용
  POST /users
• 상태 없음(stateless)
  REST는 각 요청 간 클라이언트의 상태를 서버가 유지하지 않음
• 데이터 포맷( JSON 형식을 사용해 데이터를 주고 받는다. )

Content-Type: application/json

{
  "id": 123,
  "name": "John Doe",
  "age": 30
}

 

 

🔵 SOAP 예시 

• Envelope, Header, Body 구조 

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:m="http://www.example.org">
  <soap:Header/>
  <soap:Body>
    <m:GetUser>
      <m:UserID>123</m:UserID>
    </m:GetUser>
  </soap:Body>
</soap:Envelope>

• HTTP POST 요청
  SOAP 주로 HTTP POST를 사용해 데이터를 전송
• 복잡한 구조
  SOAP 메시지는 XML 기반으로 복잡한 구조를 가질 수 있음
• 상태 보존
  SOAP은 상태 보존(Stateful) 프로토콜일 수 있으며, 상태 정보를 기억할 수 있는 메커니즘을 지원

이렇듯 REST는 리소스(데이터) 중심으로 묘사되지만, SOAP은 행위, 기능 중심으로 서술됩니다. 또한 보편적인 웹 서비스에 SOAP이 아닌 HTTP를 통한 REST를 사용하는 이유는 REST는 여러가지 형태 데이터(html, json, text)를 전송할 수 있지만, SOAP은 XML 데이터만을 고정적으로 전송할 수 있도록 만들졌기 때문입니다. 

REST는 요청과 응답에 대한 캐시를 사용할 수 있어 보다 효율적이며 SOAP에서는 사용할 수 없는 기능입니다 . 그리고, REST는 ACID 특성과 관련된 내용이 없지만 SOAP는 자체 기준이 있습니다. 

 

 

3. RESTful API 설계 원칙

REST는 설계 규칙이므로 일반적으로 널리 통용되는 규칙이 있습니다. 프로그램의 원할한 유지보수 및 개발자 사이에서의 커뮤니케이션을 원활히 돕도록 만들어진 규칙들입니다. 

 

1️⃣ Uniform Interface

REST는 API를 설계할 때 자원을 중심으로 만드는 것이 원칙입니다. 

URI 자원으로 한정된 일관적인 인터페이스(uniform interface)를 구현하는 것으로 자원 조작을 통일하는 것이 좋습니다.

 

일반적으로 HTTP를 구성하는 URL, HTTP method, Status Code를 통해 인터페이스를 구현합니다. 

• URL은 동사를 제외한, 명사로 구성합니다. 
  어떤 요청을 진행할 대상(URI)은 자원이므로, 해당 자원을 정확하게 지칭하는 명사로 구성하는 것이 좋습니다. 

BAD	GOOD
[GET] /find/users/1	[GET] /users/1
[GET] /users/show/1	[GET] /users/1
[POST] /insert/user/2	[POST] /users/2

 

• Resource에 대한 행위를 HTTP method( GET, POST, PUT, DELETE) 만으로 표현합니다. 
  어떤 작업을 수행할 것인지에 대한 혼선을 줄이기 위해 통일하는 것이 좋습니다. 

BAD	GOOD
[GET] /delete/users/1	[DELETE] /users/1
[POST] /post/products	[POST] /products

 

• URL가 길어지는 경우 - 를 사용해 가독성을 높입니다. 

BAD	GOOD
[GET] /users/1/ordered_items	[GET] /users/1/ordered-items

 

• 파일 확장자는 URL에 포함시키지 않습니다. payload에 포함되는 파일 확장자는 headers에 포함됩니다. 

BAD	GOOD
[GET] /users/1/profile-photo.jpg	[GET] /users/1/profile-photo

 

• 응답 Response의 Status Code의 기본적인 규칙을 따릅니다.
  • 200 OK: 성공적인 GET 요청에 대한 응답
  • 201 Created: 새로운 자원이 성공적으로 생성됨
  • 204 No Content: 성공적인 요청이 있었지만 응답에 컨텐츠가 없음
  • 400 Bad Request: 잘못된 요청이 전송되었음
  • 401 Unauthorized: 인증이 필요한 리소스에 인증되지 않은 상태로 접근함
  • 404 Not Found: 요청한 리소스를 찾을 수 없음
  • 500 Internal Server Error: 서버 측에서 오류가 발생함

 

3️⃣ Stateless 

상태에 대한 정보를 따로 저장하거나 관리 하지 않는 것이 (state + less) REST의 특징입니다. 

API 서버는 들어오는 요청만 단순히 처리하고, 요청에 대한 결과를 서버에 따로 저장하지 않기 때문에 이미 로그인 했는지, 주문을 했는지 서버는 알지 못합니다. 단점으로 보이지만 이런 특징 덕분에 서비스의 자유도가 높고, 서버에 불필요한 정보를 관리하지 않음으로 서비스 구현이 단순해지는 장점이 있습니다. 

 

코드의 가시성과 안정성이 확보되며 더 간편하게 확장될 수 있다는 장점이 생기는 것입니다. 

서버가 세션 정보, 쿠기 정보 또한 별도로 저장하거나 관리하지 않기 때문에 클라이언트에서 상태 정보를 항상 전송해야 합니다. 따라서 통신 비용이 높아지는 특징도 존재합니다. 

 

4️⃣ Cacheable

위의 Stateless에 통신 비용이 높아짐을 해결하기 위한 정책으로 요청에 관한 응답을 따로 저장해 추후 재사용이 가능해지는 것입니다. 클라이언트 - 서버의 상호작용을 제거해 성능 향상과 보다 확장성을 보장할 수 있게 됩니다. 추가적인 기능 생성이 아닌 기존 웹 표준을 사용해 HTTP가 기본적으로 가지고 있는 캐시 정책을 사용할 수 있습니다. 

 

요청에 대한 응답을 매번 갱신하는 것이 아닌 캐시를 이용해 데이터를 보여주는 경우 서버 측에 업데이트 된 데이터가 반영되지 않아 캐시된 데이터를 보여줄 경우 신뢰성이 감소되는 우려가 존재합니다. 

 

5️⃣ Layered System 

통신은 여러 기능이 혼재되어 있어 인터넷 규모의 요구 사항을 향상 시키기 위해 레이어드 시스템을 지키며 설계되어 있습니다. 쉽게 말해, 복잡한 여러 기능을 계층화 시켜 한 기능씩 순차적으로 진행하는 것을 의미합니다. 레이어가 여러 층으로 구성되어 특정 기능이 진행되는 동안 해당 레이어 너머 시스템을 확인할 수 없게 함으로 시스템 복잡성을 낮출 수 있습니다. 또한, 레이어 중간에 공유 중개자를 두어 로드 밸런싱 및 캐시 정책을 도입할 수 있게 해줍니다. 계층 별로 독립적인 기능을 수행하기 때문에, 특정 기능이 오래되어 교체가 필요할 때에도 새로운 서비스를 완전히 격리할 수 있습니다. 그러나 계층적으로 일이 처리되다 보면 데이터 처리에 과부하가 더해져 응답이 늦어질 수 있습니다. 

 

6️⃣ Code On Demand

서버가 네트워크를 통해 클라이언트에 전달한 Javascript 등과 같은 프로그램들은 그 자체로 실행이 될 수 있어야 합니다. 서버로부터 기능을 내려받아 클라이언트에서 바로 실행할 수 있어야 한다는 뜻입니다. 이 특징은 사전 구현에 필요한 기능의 수를 줄임으로 클라이언트를 단순화할 수 있습니다. 

 

정적 데이터를 xml 또는 Json에 담아 Client로 보내고 Client가 이 데이터를 가공하는 방식이 있습니다. 하지만 Code On Demand 원칙은 Client에 보내는 데이터를 바로 실행 가능한 코드 형태로 보내어 Client가 곧바로 실행하는 것을 말합니다. 

 

시스템 확장성이 향상되지만 오히려 클라이언트 입장에서는 실행할 코드를 백엔드에서 받기 전에 전혀 알 수가 없어 가시성이 낮아집니다. 따라서 상위 5대 원칙과 달리 선택적인 원칙으로 조직 내부에서는 사용할 수 있지만 외부에서는 사용이 불가할 수 있습니다.