RESTful API

REST API

Representational State Transfer API - 상태를 전달하는 것을 나타내는 방법

 

통신을 한다는 것을 다음과 같이 풀어서 설명하는 방법입니다. ‘특정 자원(데이터)을 어떤 방식으로 전달하는 것’으로 간주하고, 이를 표현하는 방식을 통일하여, 개발자들 사이에서 의사소통을 원활히 하고자 했죠.

REST API를 호출하는 클라이언트의 요청 형태

 

요청에는 여러 종류가 있습니다. 아래 간단한 예시들을 확인해볼까요?

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

요청을 자세히 보면 크게 두 부분으로 나뉘어 있다는 것을 알 수 있습니다. “무엇을 어떻게"의 방법입니다. 여기서 ‘무엇을’에 해당하는 특정 데이터를 resource라고 부르며 URI (Uniform Resource Indentifier)로 표현합니다. ‘어떻게 하겠다’는 동작은 동사이고, http method로 표현합니다. 

 

 

REST API 장점

 

Self-descriptiveness

여러 장점들이 있지만, 사실 그중 가장 명확한 장점은 바로 self-descriptiveness입니다. RESTful API는 그 자체만으로도 API의 목적이 쉽게 이해가 되기 때문입니다.

 

요청	RESTful API
user들의 정보를 get 하고자 함	[GET] http://localhost:8000/users
starbucks에서 1번 beverages의 정보를 get 하고자 함	[GET] http://starbucks.com/beverages/1
starbucks에서 2번 beverage를 주문하고자 함	[POST] http://starbucks.com/order - body {beverage:2}

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

 

RESTful API vs SOAP

SOAP

soap(Simple Object Access Protocol)은 XML 기반의 메세지 전송 프로토콜입니다.

• 원격 프로시저 호출 패턴 (참고자료)
• 플랫폼에 종속되지 않아 이 기종 간 통신 가능
• 헤더와 바디를 가지며 헤더에는 메타 정보, 바디에는 실제 정보가 들어가 있음
• 규약, 에러 처리, 분산 처리에 대한 옵션이 내장되어 있음

REST와 SOAP의 차이점

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

1. REST는 앞서 언급한대로 리소스(데이터) 중심으로 묘사되지만, SOAP은 행위, 기능 중심으로 서술됩니다.
2. 보편적인 웹 서비스에서 SOAP이 아닌 HTTP를 통한 REST를 사용하는 이유는 REST는 여러가지 형태의 데이터 (html, json, text)를 전송할 수 있지만, SOAP은 XML 데이터만을 고정적으로 전송하도록 만들어졌기 때문입니다.
3. 또한 REST는 요청과 응답에 대한 캐시를 사용할 수 있어 보다 효율적입니다. SOAP에서는 사용할 수 없는 기능입니다.
4. REST는 ACID 특성과 관련된 내용이 없지만 SOAP는 자체 기준이 있습니다.

RESTful API 설계 원칙

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

 

Uniform Interface

REST는 API를 설계할 때 자원을 중심으로 만드는 것이 원칙입니다. 따라서 URI 자원으로 한정된 일관적인 인터페이스 (uniform interface)를 구현하는 것으로 자원 조작을 통일하는 것이 좋습니다.

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

 

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

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

 

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

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

 

• Resource 사이에 연관 관계 및 계층 관계가 있는 경우 slash('/') 를 사용합니다.
  • /resource/고유 ID/연관 관계 있는 resource
  • ex) [GET] /users/{user_id}/profile
• URI 마지막 문자로 /를 포함하지 않습니다.

GOOD	BAD
[GET] /users/portfolios/	[GET] /users/portfolios

 

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

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

 

• 파일 확장자는 URI에 포함시키지 않습니다. 이때, payload에 포함되는 파일의 확장자는 headers에 포함됩니다.

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

• 응답 Response 의 status code의 기본적인 규칙을 따릅니다.

Client - Server

데이터를 저장하는 데이터 스토리지 부분과, 이를 활용하고 서비스를 구동하는 유저 인터페이스를 분리하는 것을 말합니다. 서버는 API를 제공하는 역할만 수행하고, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보등)를 직접 관리합니다.

클라이언트와 서버가 명확히 분리되어 있지 않고, 서버에서 html,css를 모두 만들어서 사용자에게 제공하던 과거와는 달리 클라이언트(프론트엔드)와 서버(백엔드)에서 개발해야할 내용이 명확해졌기 때문에 서로의 의존성이 줄어들었습니다. 이는 각자 신경써야 하는 개발 분야가 달라졌음을 의미하고 (관심사의 분리), 따라서 독립적인 개발이 가능해졌습니다.

개별 부분의 발전에 있어 다른 부분이 영향을 주지 않는다는 장점이 생겼습니다.

 

Stateless

한 번 로그인한 정보를 서버에서 영원히 알고 있으면 얼마나 편리할까요? 그렇나 REST에서는 그런 일은 없습니다. 상태에 대한 정보를 따로 저장하거나 관리 하지 않는 것이 (state + less) REST의 특징입니다.

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

코드의 가시성과 안정성이 확보되고, 더 간편하게 확장될 수 있다는 장점이 생깁니다. 서버가 세션 정보, 쿠키 정보 또한 별도로 저장하거나 관리하지 않기 때문에 클라이언트에서 상태 정보를 항상 전송해야합니다. 따라서 통신 비용이 높아지는 특징이 있습니다.

Cacheable

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

요청에 대한 응답을 매번 갱신하는 것이 아니기 때문에, 캐시를 이용하여 데이터를 보여줄 경우 서버측에서 업데이트된 데이터가 반영되지 않고, 캐시된 데이터를 보여줄 경우 신뢰성을 감소시킬 우려가 있습니다.

 

Layered System

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

 

Code on Demand

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

정적인 데이터를 xml 또는 json에 담아서 client로 보내고 client가 이 데이터를 가공하는 방식이 있습니다. 그러나 code on demand 원칙은 client에 보내는 데이터를 바로 실행 가능한 코드의 형태도 보내어 client가 곧바로 실행하는 것을 말합니다.

시스템 확장성이 향상되지만, 오히려 클라이언트 입장에서는 실행할 코드를 백엔드에서 받기 전에는 전혀 알 수가 없기 때문에 가시성이 낮아집니다. 따라서 상위 5대 원칙과는 달리 선택적인 원칙입니다.

조직 내부에서는 사용 가능하지만, 외부에서는 사용이 불가능할 수 있습니다.

 

 

 

이렇게 RESTful API 를 공부해 보았는데요. 사실 query parameter 와 path parameter에 대하여 공부해야 비로소 데이터 정제에 한 발자국 다가갔다라고 할 수 있겠습니다.

다음 시간에 query parameter 와 path parameter를 공부해 보아요.