Web API vs Rest API

yunajoe 2023. 1. 1. 10:52

우리가 어떤 리퀘스트를 보냈을 때, 무슨 리스폰스를 받는지는 모두 그 서비스를 만드는
개발자들이 정하는 부분입니다. 잠깐 실제 개발 현장에서 일어나는 이야기를 해볼게요.
개발자에는 크게 두 가지 종류가 있습니다.
첫 번째는 사용자가 직접 서비스 화면을 보는 웹 페이지나 앱 등을 만드는 프론트엔드(Front-end) 개발자,
두 번째는 웹 브라우저나 앱이 보내는 리퀘스트를 받아서 적절한 처리를 한 후 리스폰스를
주는 서버의 프로그램을 만드는 백엔드(Back-end) 개발자

WEB API

- Web API를 설계한다는 것은 서비스에서 사용될 모든 URL들을 나열하고, 각각의 URL에 관한 예상 리퀘스트와 리스폰의 내용을 정리한다는 뜻

- WEB API가 설계되고 나면, 그때 프론트엔드/백엔드 개발자들이 해당 설계에 맞게 각자 코드를 작성하기 시작. 설계와 개발이 동시에 진행되기도 하고, 설계 내용이 중간에 수정되기도 한다

- 문제는 Web API는 어떻게 설계해도 동작하는데는 아무런 지장이 없다. 즉 기능적으로는 아무런 문제가 없다고 해도 Web API를 아무렇게나 설계해도 되는 것은 아닌다. Web API가 잘 설계되었는지에 관한 기준으로는 보통 REST API를 기준으로 평가한다. 많은 개발자들이 Web API를 개발할 때 REST API를 준수하기 위해 노력한다

예를 들어 어떤 회사에서는 직원 추가 기능을 아래와 같이 한다

(1) 'https://learn.codeit.kr/api/members' URL로  
(2) 리퀘스트의 헤드에 POST 메소드를 설정하고,
(3) 리퀘스트의 바디에 새 직원 정보를 넣어서 보내면 된다

또 다른 회사는 지원 추가 기능을 아래와 같이 한다

(1)'https://learn.codeit.kr/api/members' URL로
(2) 리퀘스트의 헤더에 GET 메소드를 설정하고,
(3) 리퀘스트의 바디에 새 직원 정보를 넣어서 보내면 된다

WEB API 설계 예시

// 예를 들어 URL(https://learn.codeit.kr/api/members)에서 직원 정보 추가 기능을 설계한다면

(1) Request
- Head
Method : POST
...

- Body
{
 "name": "Jerry",
 "email: "jerry@codeitshopping.kr",
 "department": "engineering",
}
...

(2) Response
Success인 경우 :
- Head
...
- Body
{
 "id": "[부여된 고유 식별자 값]",
 "name": "Jerry",
 "email": "jerry@codeshopping.kr"
 "department": "engineering",
}

Fail인 경우 :
...

REST API

- REST API는 오늘날 많은 웹 개발자들이 Web API 설계를 할 때, 준수하기 위해 노력하는 일종의 가이드라인

REST API구성

구성 요소	내용	표현방법
자원(resource)	자원	URI(엔드포인트)
행위(verb)	자원에 대한 행위	HTTP 요청 메서드
표현(representations)	자원에 대한 행위의 구체적 내용	페이로드

REST API 설계 원칙

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

- 리소스를 식별할 수 있는 이름은 동사보다는 명사를 사용한다. 따라서 get같은 행위에 대한 표현이 들어가서는 안된다

# bad 
Get / getTodo/1


# good 
Get / todos/1

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

- HTTP 요청 메서드는 클라이언트가 서버에게 요청의 종류와 목적(리소스에 대한 행위)을 알리는 방법

- 주로 5가지 요청 메서드(GET, POST, PUT, DELETE)를 사용하여 CRUD를 구현한다

HTTP요청메서드	종류	목적	페이로드

REST API를 이해하기 위해서는
REST architecture란 미국의 컴퓨터 과학자인
Roy Fielding이 본인의 박사 논문 'Architectural Styles and the Design
of Network-based Software Architectures'에서 제시한 개념인데요.
그는 웹이 갖추어야 할 이상적인 아키텍처(구조)로 REST architecture라는 개념을 제시

REST는 Representational State Transfer(표현적인 상태 이전)의 줄임말로,
해석하면 '표현적인, 상태 이전'이라는 뜻
예를 들어..
웹을 하나의 거대한 컴퓨터 프로그램이라고 생각한다면, 각각의 웹 페이지는
그 프로그램의 내부 상태를 나타낸다고 할 수 있습니다.
그렇다면 우리가 웹 페이지들을 계속 옮겨 다니면서 보게 되는 내용은,
웹이라는 프로그램의 매번 새로운 상태를 나타내는 표현

그럼 REST architecture가 되기 위한 조건에는 어떤 것들이 있을까요?
다음과 같은 6가지 기준을 충족하면 REST architecture로 인정

Client-Server
Stateless
Cache
Uniform Interface
Layered System
Code on Demand

1. (Client-Server) Client-Server 구조를 통해 양측의 관심사를 분리해야 합니다.
현재 토픽에서는 웹 브라우저가 실행되고 있는 컴퓨터가 Client, 서비스를 제공하는
컴퓨터가 Server에 해당하는데요. 이렇게 분리를 해놓으면 Client 측은 사용자에게 어떻게 하면
더 좋은 화면을 보여줄지, 다양한 기기에 어떻게 적절하게 대처해야할지 등의 문제에 집중할 수 있고,
Server 측은 서비스에 적합한 구조, 확장 가능한 구조를 어떻게 구축할 것인지 등의 문제에 집중할 수 있습니다.
이렇게 각자가 서로를 신경쓰지 않고 독립적으로 운영될 수 있는 겁니다.

2. (Stateless) Client가 보낸 각 리퀘스트에 관해서 Server는
그 어떤 맥락(context)도 저장하지 않습니다.
즉, 매 리퀘스트는 각각 독립적인 것으로 취급된다는
뜻입니다.
이 때문에 리퀘스트에는 항상 필요한 모든 정보가 담겨야합니다.

3. (Cache) Cache를 활용해서 네트워크 비용을 절감해야 합니다.
Server는 리스폰스에, Client가 리스폰스를 재활용해도 되는지
여부(Cacheable)를 담아서 보내야합니다.

4.
Client가 Server와 통신하는 인터페이스는 다음과 같은 하위 조건 4가지를 준수해야 합니다.
이 조건이 REST API와 연관이 깊은 조건

4-1) identification of resource
리소스(resource)는 웹상에 존재하는 데이터를 나타내는 용어인데요.
저도 이번 노트에서는 리소스라는 용어를 사용

4-2)
Client와 Server는 둘 다 리소스를 직접적으로 다루는 게 아니라 리소스의 '표현(representations)'을 다뤄야 합니다. 예를 들어, Server에 '오늘 날씨'(/today/weather)라는 리소스를 요청했을 때, 어떤 Client는 HTML 파일을 받을 수도 있고,
어떤 Client는 이미지 파일인 PNG 파일을 받도록 구현

4-3)
self-descriptive messages : self-descriptive는 '자기설명적인'이라는 뜻인데요.
위에서 살펴본 2. Stateless 조건 때문에 Client는 매 리퀘스트마다 필요한 모든 정보를 담아서
전송해야 합니다. 그리고 이때 Client의 리퀘스트와
Server의 리스폰스 모두 그 자체에 있는 정보만으로 모든 것을 해석할 수 있어야 한다는 뜻
4-4)
이 조건은 웹을 하나의 프로그램으로 간주했을 때, Server의 리스폰스에는 현재 상태에서 다른 상태로 이전할 수 있는 링크를 포함하고 있어야 한다는 조건입니다. 즉, 리스폰스에는 리소스의 표현, 각종 메타 정보들뿐만 아니라 계속 새로운 상태로 넘어갈 수 있도록 해주는 링크들도 포함되어 있어야 한다는 거죠
5.
(Layered System) Client와 Server 사이에는 프록시(proxy),
게이트웨이(gateway)와 같은 중간 매개 요소를 두고, 보안, 로드 밸런싱 등을 수행할 수 있어야 합니다.
이를 통해 Client와 Server 사이에는 계층형 층(hierarchical layers)들이 형성됩니다.

6
(Code-On-Demand) Client는 받아서 바로 실행할 수 있는 applet이나 script 파일을 Server로부터 받을 수 있어야 합니다. 이 조건은 Optional한 조건으로 REST architecture가 되기 위해 이 조건이 반드시 만족될 필요는 없습니다.
==========================
feat. API란?!
Application Programming Interface의 약자로, 원래는 '개발할 때 사용할 수 있도록
특정 라이브러리나 플랫폼 등이 제공하는 데이터나 함수 등'을 의