REST와 RESTful API: 차이점과 설계 원칙

일어나 개발해야지·2024년 12월 30일

REST 와 RESTful

REST와 RESTful 은 어떻게 다를까 ?
먼저 API라고 함은 요청과 응답을 주고 받기 위한 약속이며
REST는 요청과 응답을 어떻게 주고 받을지에 대한 약속의 선택지 중 하나이다.
그와중에 RESTful 하다는 것은 REST의 원칙을 잘 지키고 있다는 표현이다.

① API: 요청(Request)과 응답(Response)을 주고받기 위한 약속(통신 규칙)
② REST : HTTP 프로토콜을 기반으로 설계된 디자인
③ RESTful : REST 원칙을 성실하게 지킨 디자인

RESTful 의 기준

RESTful 하다고 말하려면 어떤 조건을 충족해야할까?
두 개념 모두 REST의 원칙을 따르는 공통점을 가지고 있으나 스타일만 따르는지, 여러원칙을 성실히 지키는지 여부에 따라, REST api와 RESTful api를 구분짓고 있다.
다만 "최대한", "성실히", "권장됨" 등의 표현으로 볼때, 그 기준이 다소 모호하다는 점을 짐작할 수 있다.

구분	REST API	RESTful API
정의	REST 스타일을 따르는 API 전반	REST 원칙을 최대한 따르는 API
설계 원칙 준수	일부만 준수해도 REST API라고 할 수 있음	REST 설계 원칙을 성실히 준수함
HATEOAS 지원	필수 아님	이상적인 RESTful API에서는 권장됨
일관성	일부 비일관적인 설계가 포함될 수 있음	설계가 일관되고 명확함

					* HATEOAS : Hypermedia As The Engine Of Application State
                                클라이언트와 서버 간의 동적 상호작용을 지원하기 위한 원칙

"REST의 기본원칙을 성실하게 지킨 서비스 디자인을 RESTful 이라고 표현한다"

REST API 의 등장배경

REST API는 어떻게 나오게 되었나 ?

1.초기 API 방식

2000년대 초반 Web 2.0의 시대가 열리면서 REST API는 주목받기 시작했다.
REST API 이전에는 SOAP와 XML-RPC이라는 API 방식를 사용했었다.
웹 서비스를 구현하는 데 사용되었던 초기 기술로 각 기술을 아래와 같은 특징을 가지고 있다.

SOAP

* 다양한 프로토콜을 지원하나, 이를 구현하기 위한 복잡한 설정과 규칙이 존재
* 클라이언트의 상태를 저장하는 방식은 서버에 부하와 확장성에 문제가 발생하기 쉬운 구조
* SOAP는 강력하지만 지나치게 무겁고 복잡한 아키텍처였다

SOAP 특징	설명	단점
XML 기반의 데이터 형식 사용	-	REST에서 사용하는 JSON에 비해 무거움
HTTP 외 다양한 프로토콜 지원	SMTP(이메일 전송), JMS(메시지 큐), FTP 전송가능	추가 프로토콜에 대한 작업이 복잡함
엄격한 통신 규칙을 정의하고 있음	보안, 트랜잭션 관리, 오류 처리 등 여러 규격 존재	여러 규격을 따라야하기 때문에 초기 설정에 시간이 많이 소요됨
상태를 저장하거나 공유하는 방식 지원	요청에 대한 상태 정보를 서버에서 유지(ex: 로그인한 상태)	서버 부하와 확장성에 문제가 생길 수 있음
*WSDL에 API의 요청과 응답에 대한 규칙 정의 필요	서버 측의 설명서	서버 측에서 작성하는 작업과 클라이언트 측에서 해석하는 작업 필요

* WSDL: Web Services Description Language

XML-RPC

* SOAP는 보다는 단순하며, 상대적으로 가볍고 간단한 구조
* 메서드 호출 중심으로 설계되어 자원에 대한 URI가 없었음
* 자원의 관리가 비효율적 이였으며, 시스템의 규모가 커질때 혼란을 초래하기 쉬운 아키텍쳐

XML-RPC 특징	설명	단점
XML 기반의 데이터 형식 사용	요청과 응답 데이터를 XML 형식으로 표현	XML은 무겁고 파싱이 복잡하여 성능 저하를 초래
원격 프로시저 호출 방식(RPC)	클라이언트가 서버의 특정 메서드를 호출하도록 설계	자원 중심이 아닌 함수 호출 방식으로 확장성과 유연성 부족
간단한 구조	SOAP보다 단순하며, 기본적인 요청/응답만 지원	복잡한 기능(보안, 트랜잭션 관리 등)을 지원하지 않음
HTTP를 전송 프로토콜로 사용	HTTP를 통해 데이터를 주고받음	REST처럼 다양한 HTTP 메서드(GET, POST 등)를 활용하지 못함
메서드 중심 설계	요청 메시지에 호출할 메서드 이름과 인자를 포함	자원의 URI 설계가 없어 대규모 시스템에서 비효율적

2.초기 API 방식의 한계점

REST 등장 이전의 초기 기술들은 다양한 규격을 따라야했기에, 상대적으로 복잡했다
XML기반의 데이터는 무겁기 때문에 데이터 처리 비용이 컸다.
모바일 앱처럼 경량화가 필요한 환경에는 대응이 어려웠다.
서버와 클라이언트를 구분하며 단순하고 확장성있는 API에 대한 니즈가 생겨났다.

REST API 원칙이란

Background

REST API에 대해서는 Roy Fielding의 박사학위 논문(2000)에서 처음 소개된 개념

Web 2.0 이 시작되던 시기로 사용자와의 상호작용을 할수 있는 동적 웹의 증가

HTTP 프로토콜을 기반으로 설계된 디자인으로 직관적이고 단순한 설계가 가능해짐

JSON을 사용함으로 경량화된 API였기에, 이후 모바일 환경에도 적용이 가능

업계 표준 가이드 라인으로는 Microsoft REST API Guidelines 이나 Google API Design Guide 이 권장되는 추세

원본 논문에 대한 해석의 차이와 실무에서 이해관계가 다르기에 표준규약이 없는 상태

자료 중심으로 정리했을때 6개의 주요 원칙과 2개의 권장 사항이 있다고 해석

1. 클라이언트 & 서버 구조

클라이언트와 서버는 분리된 역할을 가지며, 서로 독립적으로 설계 해야한다.

2. URI는 리소스를 표현하는데 집중한다.

고유한 URI를 가진다.

3. 행위는 HTTP 메소드로 정의한다.

GET / POST / PUT / PETCH / DELETE

URI 와 HTTP 메소드의 역할은 구분되어야 한다.

4. 상태 코드 사용 - HTTP Status Codes

Clinet 요청 결과를 코드를 반환하여, 명확한 피드백을 제공

400 번대 Error Code

번호 상태 코드 설명
401 Unauthorized 인증 정보 누락 (Authorization 헤더 없이 요청한 경우)
403 Forbidden 리소스에 접근 권한 없음 (관리자 권한이 필요한 경우)
404 Not Found 요청한 리소스나 엔드포인트를 서버에서 찾을 수 없음
410 Gone 리소스가 영구적으로 삭제된 경우
429 Too Many Requests 클라이언트가 정해진 요청 한도를 초과했을 때 발생

번호	상태 코드	설명
401	Unauthorized	인증 정보 누락 (Authorization 헤더 없이 요청한 경우)
403	Forbidden	리소스에 접근 권한 없음 (관리자 권한이 필요한 경우)
404	Not Found	요청한 리소스나 엔드포인트를 서버에서 찾을 수 없음
410	Gone	리소스가 영구적으로 삭제된 경우
429	Too Many Requests	클라이언트가 정해진 요청 한도를 초과했을 때 발생

5. 상태 비저장성 (Stateless)

Statefull

* 서버가 클라이언트의 상태를 기억함
* 이전 요청 정보를 현재 요청에 반영 가능하기 때문에 요청들 사이에 연속성이 생긴다.
* 어뜻 듣기에는 Statefull 유용해 보이나, 서버의 분산이 어려워지고 
* 확장성과 유연성에 한계가 생긴다는 단점이 있다.

Stateless

* Statefull의 반대 개념으로, 서버는 클라이언트의 상태를 저장하지 않는다.
* 이전에 어떤 요청을 했는지 기억하지 않고, 요청이 있을때마다 필요한 모든 정보를 제공합니다.
* 설계가 단순해지기 때문에, 확장성과 안정성에 장점이 있다. 
* 다만 같은 요청을 많이 받게되는 단점이 있다.

어플리케이션이 상태를 기억(Statefull) 하고 있다고 느끼는 순간들이 있다.

로그인 정보가 유지된다거나,
뎁스가 깊은 화면에서 이전 내용이 불러와 지는 경우 등
관련 정보는 Client에 저장해서 활용하는 경우가 많다.
정리하자면 클라이언트는 여러 저장소(상태관리 라이브러리, 로컬스토리지, 세션스토리지, 쿠키)를 활용해서 Statefull 하게 동작하는 경우가 있다.
하지만, 서버는 상태를 기억하지 않는다 .

6. 캐시 가능성

클라이언트는 서버로 부터 받은 응답을 캐시하고, 동일한 요청에 대해서 
캐시된 내용을 사용하여 성능 최적화와 네트워크 대역폭 절약하여 트래픽을 줄일 수 있다.

서버는 클라이언트의 상태를 저장하지 않으나,
클라이언트는 같은 요청에 대해서 서버의 응답을 캐싱하여 사용할수 있다.

7. 계층화 시스템(권장)

* 서버를 다중 계층으로 구성할 수 있다.
* 클라이언트는 자신이 요청하는 리소스가 서버에서 제공되는지 중간계층에서 제공되는지에 알수 없다.
* 중간계층을 추가하거나 변경해도 클라이언트에 영향을 미치지 않기 때문에 독립적으로 확장하거나 교체할 수 있다.

8. HATEOAS(권장)

* 클라이언트는 API의 응답에서 제공된 하이퍼미디어 링크를 따라 리소스 간 탐색을 수행
* 응답에 링크를 포함하여 클라이언트가 API 탐색이 가능하도록 만듬
* REST의 이론적인 원칙에서 강조되지만, 실무에서는 거의 사용되지 않거나 선택적으로 사용됨

{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "links": [
    {
      "rel": "self",
      "href": "http://api.example.com/users/123",
      "method": "GET"
    },
    {
      "rel": "update",
      "href": "http://api.example.com/users/123",
      "method": "PUT"
    },
    {
      "rel": "delete",
      "href": "http://api.example.com/users/123",
      "method": "DELETE"
    },
    {
      "rel": "orders",
      "href": "http://api.example.com/users/123/orders",
      "method": "GET"
    }
  ]
}

RESTful API 체크리스트

리소스 중심으로 설계되어있는가 ?
HTTP 메서드가 요청의도에 따라 일관되게 사용되고 있는가 ?
서버가 클라이언트 상태를 저장하지 않는가 ?
적절한 상태 코드를 사용하고 있는가 ?
HATEOAS 지원 응담에 링크(href or links)를 포함하여 리소스 간에 탐색성을 제공하고 있는가 ?

Small Question

1. RESTful API의 기준이 모호한 이유는 ?

REST는 설계 원칙이지, 표준이 아니다.
일부 원칙들은 이상적이지만 제약조건을 따르기 어렵거나, 불필요한 경우가 많기 때문
완벽히 준수하지 않아도 RESTful로 간주되는 경우가 많다.

2. URI 와 URL 그리고 EndPoint

https://api.example.com/api/notes/1

URI (Uniform resource Identifier) - 리소스를 식별하는데 중점을 둠
ᄂ URL (Uniform resource Locator) - URI의 한 종류로, 리소스가 어디에 위치하는지 나타냄
ᄂ URN (Uniform resource Name) - URI의 한 종류로, 리소스의 이름을 알려줌
EndPoint - URI와 HTTP 메서드를 조합하여 정의 GET /api/notes

sample URI는 REST API 맥락에서는 리소스를 식별하는 용도로 사용되기에 URI라고 표현하는게 맞지만, 상황에 따라서는 리소스의 위치를 표현하기도 하기때문에 URL이라고 표현해도 잘못된 표현은 아님. 다만 URL 보다 URI가 더 넓은 개념임을 이해하는게 중요함

참고자료

일어나 개발해야지

이전 포스트

RN | facebook login - App freezing (with node version)

다음 포스트