rest.md

REST/RESTful API

REST

REpresentational State Transfer의 약자로, 컴퓨터 사이언스 분야에서 개발된 소프트웨어 아키텍처 스타일이다.
이는 웹의 장점을 최대한 활용할 수 있도록,
2000년 로이 필딩이 웹의 기본 원칙과 웹 아키텍처의 개념을 바탕으로 설계되었다.

크게, REST는 자원(Resource)을 표현하고,
자원에 대한 상태(State)를 전달하고 ,
클라이언트와 서버 간의 통신을 위한 표준 HTTP 메소드(GET, POST, PUT, DELETE 등)를 사용한다.

등장배경

• 애플리케이션 분리 및 통합
• 다양한 클라이언트의 등장
• 멀티 플랫폼에 대한 지원을 위해 서비스 자원에 대한 아키텍처를 세우고 이용하는 방법을 모색한 결과, REST에 관심을 가지게 되었다.

특징

(1) 클라이언트-서버(Client-Server) 구조

REST는 클라이언트와 서버 간의 역할을 명확하게 분리한다.

• 서버는 데이터와 비즈니스 로직을 관리하고 제공하며,
  클라이언트는 사용자 인터페이스와 사용자 상호작용을 담당
• 클라이언트와 서버 간의 독립성이 향상되고, 서로의 변경이 다른 시스템에 영향주지 않음

(2) 무상태성(Stateless)

클라이언트와 서버 간의 통신에서 상태 정보를 서버가 유지하지 않는 것을 의미
즉, 각 요청은 독립적으로 처리되며, 이전 요청의 상태나 컨텍스트에 대한 정보를 서버가 보관하지 않는다.

상태 : 클라이언트의 세션정보, 인증 상태, 이전 요청의 결과 등

• 클라이언트는 상태 정보를 유지하지 않고도 서버에 요청을 보낼 수 있다.

  • 클라이언트는 각각의 요청에서 필요한 모든 정보를 제공하고, 서버의 상태나 컨텍스트에 의존하지 않는다. 클라이언트의 자율성 향상

• 서버는 클라이언트의 상태 정보를 유지할 필요가 없기 때문에, 클라이언트의 요청을 독립적으로 처리할 수 있다.

  • 이는 여러 클라이언트 요청을 동시에 처리하는 장점을 가진다. 서버의 확장성 향상

단점으로는 반복되는 요청으로 인해 네트워크 성능 저하가 일어날 수 있고, 서버의 일관된 관리를 받을 수 없다는 점이 있다.

(3) 캐싱(Cache)

REST는 HTTP 프로토콜을 기반으로 하므로, 웹의 캐싱 기능을 활용할 수 있다.

• 서버는 응답을 캐싱하여 동일한 요청에 대해 중복작업을 피해 성능을 향상시킨다.
• 클라이언트는 캐시된 응답을 재사용하여 네트워크 대역폭을 절약한다.

(4) 균일한 인터페이스(Uniform Interface)

REST는 일관된 인터페이스를 제공한다.
리소스는 고유한 URI로 식별되며, HTTP 메소드(GET, POST, PUT, DELETE 등)를 사용하여 리소스에 대한 조작을 수행한다.

• 리소스에 대한 조작은 표준화되어 있어 클라이언트와 서버 간의 상호 운용성을 높이고, 시스템의 확장성을 향상시킨다.

(5) 계층형 구조(Layered System)

REST 아키텍처는 계층화 구조를 허용한다.

• 서버는 다른서버나 프록시 서버에 대한 요청을 전달하고, 중간서버는 요청을 중계하거나 필터링 하여 보안 및 로드 밸런싱을 수행할 수 있다.
  • 시스템의 확장성과 유연성 향상

REST의 장단점

장점

• HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API 사용을 위한 별도의 인프라를 구출할 필요가 없다.
• HTTP 프로토콜의 표준을 최대한 활용하여 여러 추가적인 장점을 함께 - 가져갈 수 있게 해준다. H- TTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.
• Hypermedia API의 기본을 충실히 지키면서 범용성을 보장한다.
• REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있다.
• 여러가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다. 서버와 클라이언트의 역할을 명확하게 분리한다.

단점

• 표준이 존재하지 않는다.
• 사용할 수 있는 메소드가 4가지 밖에 없다.HTTP Method 형태가 제한적이다.
• 구형 브라우저가 아직 제대로 지원해주지 못하는 부분이 존재한다.
  • PUT, DELETE를 사용하지 못하는 점
  • pushState를 지원하지 않는 점

REST API

이러한 REST를 기반으로 구현한 API를 REST API라고 하며, 몇 가지 규칙이 있다.

REST API 중심 규칙

(1) URI는 정보의 자원을 표현해야 한다.

# 1번 user의 정보를 요청한다면
GET /users/1 ⭕
GET /users/get/1 ❌

자원 외에 행위가 포함되는 것은 적절하지 않다.

(2) 자원에 대한 행위는 HTTP Method(GET, POST, PUT, PATCH, DELETE)로 표현한다.

# 새로운 user를 등록할 때
POST /users/register ⭕
GET  /users/register ❌

새로운 user 등록은 자원을 작성하는 행위이므로 POST가 알맞다. GET은 데이터를 가져오는것을 의미한다.

PUT은 전체 데이터 수정, PATCH는 일부 데이터 수정, DELETE는 데이터 삭제를 의미하므로, 그것에 맞춰 Method를 사용한다.

REST API 설계 규칙

(1) 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용, URI 마지막 문자로 슬래시(/)를 포함하지 않는다.

http://example.com/users/1/resume
http://example.com/notices

http://example.com/users/register/ ❌
http://example.com/users/register  ⭕

URI의 모든 글자는 자원의 유일한 식별자 역할을 하며, URI가 다르면 자원도 달라야 한다. 통신에 혼동을 주지 않기 위해 분명한 URI를 사용해야 하며, 따라서 마지막에는 /를 포함하지 않는다.

(2) 밑줄(_) 보다는 하이픈(-) 사용

밑줄(_)은 UI에 따라 가려지기도 하고 보기 어려우므로 대신 하이픈(-)을 사용하여 가독성을 높인다.

http://example.com/posts/밑줄_보다는_하이픈_사용 ❌
http://example.com/posts/밑줄-보다는-하이픈-사용 ⭕

(3) URI 경로에는 소문자가 적합

**RFC 3986(URI 문법 형식)**은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문에 URI 경로에 대문자 사용은 피하도록 해야 한다. 대소문자에 따라 다른 리소스로 인식한다.

http://example.com/users/Register ❌
http://example.com/users/register ⭕

(4) 파일 확장자는 URI에 포함하지 않음

자원 포맷을 나타내는 파일 확장자는 URI 대신 Accept header를 사용한다.

http://example.com/users/1/resume/photo.jpg ❌
GET /users/1/resume/photo HTTP/1.1 Host: example.com Accept: image/jpg ⭕

(5) 리소스 간의 관계를 표현

리소스 간에 관계가 있는 경우, /리소스명/리소스 ID/관계가 있는 다른 리소스명으로 URI를 구성한다.

GET : /users/{userid}/resume (일반적으로 소유 ‘has’의 관계를 표현할 때)

HTTP 응답 상태 코드

잘 설계된 REST API는 응답 코드 역시 적절하게 전송해야 한다.

코드	설명
1xx	정보 응답
2xx	성공 응답
3xx	리다이렉트
4xx	클라이언트 요청 오류
5xx	서버 오류

coco3o - HTTP 상태 코드 정리

RESTful API

위와 같은 REST API 규칙을 잘 지켜 설계한 API를 RESTful한 API라고 한다. RESTful을 강조하는 이유는 이해와 사용이 쉬운 API를 설계하기 위함이다.

성능 보다는 API에 대한 이해와 호환성에 맞춘 것이므로, 성능이 중요하다면 무조건 지켜야 할 사항은 아니다.

참고자료 :
https://owni14.github.io/dev/etc-02-what-is-api.html
https://dev-coco.tistory.com/98