REST API란? REST, RESTful이란?

REST API란 REST를 기반으로 만들어진 API를 의미합니다. REST API를 알기 위해 REST부터 알아보도록 하겠습니다.

REST란?

REST(REpresentational State Transfer)의 약자로 자원을 이름으로 구분하여 해당 자원의 상태를 주고받는 모든 것을 의미합니다.
REST는 HTTP를 기반으로 클라이언트가 서버의 리소스에 접근하는 방식을 규정한 아키텍쳐
REpresentational State Transfer의 약자로 전반적인 웹 어플리케이션에서 상호작용하는데 사용되는 웹 아키텍쳐 모델이다. 즉, 자원을 주고받는 웹 상에서의 통신 체계에 있어서 범용적인 스타일을 규정한 아키텍쳐 라고 할 수 있다.

API란 무엇인가?

Application Programming Interface의 약자로 구글 맵 API, 카카오 비전 API 등 기존에 있는 응용 프로그램을 통해서 데이터를 제공받거나 기능을 사용하고자 할 때 사용하는 인터페이스 및 규격을 말한다. API는 프로그래밍 언어, 운영체제 등에서도 사용되는 범용적인 용어이다. 따라서, REST API라는 것은 REST 원칙을 적용하여 서비스 API를 설계한 것을 말하며 대부분의 서비스가 REST API를 제공한다.

REST란?

HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고,
HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원(URI)에 대한 CRUD Operation을 적용하는 것을 의미합니다.

CRUD Operation이란

CRUD는 대부분의 컴퓨터 소프트웨어가 가지는 기본적인 데이터 처리 기능인 Create(생성), Read(읽기), Update(갱신), Delete(삭제)를 묶어서 일컫는 말로
REST에서의 CRUD Operation 동작 예시는 다음과 같다.

Create : 데이터 생성(POST)
Read : 데이터 조회(GET)
Update : 데이터 수정(PUT)
Delete : 데이터 삭제(DELETE)

---

REST 구성 요소

REST는 다음과 같은 3가지로 구성이 되어있다.

1. 자원(Resource) : HTTP URI

2. 자원에 대한 행위(Verb) : HTTP Method

3. 자원에 대한 행위의 내용 (Representations) : HTTP Message Pay Load

REST는 자체 표현 구조로 구성되어 REST API 만으로 HTTP 요청의 내용을 이해할 수 있다.

REST의 특징

균등한 인터페이스 (Uniform Interface)

REST가 HTTP의 표준만 따른다면 어떠한 기술이던지 접목하여 사용할 수 있기 때문에 플랫폼이나 언어의 제약에 구애받지 않는다. 요즘은 REST API를 정의할 때 JSON(JavaScript Object Notation) 방식을 가장 많이 사용하지만 XML(eXtensible Markup Language)도 적용할 수 있다.

무상태성 (Stateless)

서버는 클라이언트의 상황을 고려하지 않고 API 요청에 대해서만 처리하기 때문에 이를 "상태가 없다" 라고 표현한다. 이렇게 되면 클라이언트를 고려하지 않아도 되기 때문에 구현이 간결해진다.

캐싱 가능 (Cacheable)

REST는 HTTP 표준을 기반으로 만들어졌기 때문에 HTTP의 특징인 캐싱을 사용할 수 있다. REST API를 활용하여 GET 메소드를 Last-Modified 값과 함께 보낼 경우, 컨텐츠의 변화가 없을 때 캐시된 값을 사용하게 된다. 이렇게 되면 네트워크 응답시간 뿐만 아니라 API 서버에 요청을 발생시키지 않기 때문에 부담이 덜 하다는 장점 또한 가지게 된다.

자체 표현성 (Self-Descriptiveness)

REST API의 자원명시 규칙 및 메소드는 그 자체로 의미를 지니기 때문에 어떠한 요청에 있어서 그 요청 자체로 어떤 것을 표현하는지 알아보기 쉽다. 물론 API를 규정한 각 서비스들이 문서를 제공하지만 이 특성에 따라서 요청하는 방식만으로 어떠한 의미인지 알 수 있어야 좋은 REST API라고 할 수 있다.

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

REST 서버가 API를 제공하는 방식이기 때문에 클라이언트에서 처리하는 부분과 독립적으로 동작한다. 따라서, 서로간의 의존성이 줄어들고 클라이언트와 서버를 최대한 독립적으로 개발할 수 있도록 도와준다.

계층형 구조 (Layered System)

클라이언트는 계층형 구조가 불가능하지만 REST 서버의 경우, 보안/로드 밸런싱/암호화 등을 추가할 수 있고 Proxy 및 게이트웨이 등의 중간매체를 사용할 수 있다.

REST API 설계 원칙

REST에서 가장 중요한 기본적인 원칙은 두 가지다. URI는 리소스를 표현하는 데 집중하고 행위에 대한 정의 HTTP 요청 메서드를 통해 하는 것이 RESTful API를 설계하는 중심 규칙이다.

1. URI는 리소스를 표현해야 한다.
   URI는 리소스를 표현하는 데 중점을 두어야 한다. 리소스를 식별할 수 있는 이름은 동사보다는 명사를 사용한다. 따라서 이름에 get 같은 행위에 대한 표현이 들어가서는 안 된다.

# bad
GET /geTodos/1
GET /todos/show/1

# good
GET /todos/1

2. 리소스에 대한 행위는 HTTP 요청 메서드로 표현한다.
   HTTP 요청 메서드는 클라이언트가 서버에게 요청의 종류와 목적(리소스에 대한 행위)을 알리는 방법이다.
   주로 5가지 요청 메서드(GET, POST, PUT, PATCH, DELETE 등)를 사용하여 CRUD를 구현한다.

   GET index/retrieve 모든/특정 리소스 취득
   POST create 리소스 생성
   PUT replace 리소스의 전체 교체
   PATCH modify 리소스의 일부 수정
   DELETE delete 모든/특정 리소스 삭제

리소스에 대한 행위는 HTTP 요청 메서드를 통해 표현하며 URL에 표현하지 않는다. 예를 들어, 리소스를 취득하는 경우에는 GET, 리소스를 삭제하는 경우에는 DELETE를 사용하여 리소스에 대한 행위를 명확히 표현한다.

# bad
GET /todos/delete/1

# good
DELETE /todos/1

REST의 장단점

장점

• HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API 사용을 위한 별도의 인프라를 구출할 필요가 없다.

• HTTP 프로토콜의 표준을 최대한 활용하여 여러 추가적인 장점을 함께 가져갈 수 있게 해 준다.

• HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.

• Hypermedia API의 기본을 충실히 지키면서 범용성을 보장한다.

• REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있다.

• 여러 가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다.

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

단점

• 표준이 자체가 존재하지 않아 정의가 필요하다.

• 사용할 수 있는 메소드가 4가지밖에 없다.

• HTTP Method 형태가 제한적이다.

• 브라우저를 통해 테스트할 일이 많은 서비스라면 쉽게 고칠 수 있는 URL보다 Header 정보의 값을 처리해야 하므로 전문성이 요구된다.

• 구형 브라우저에서 호환이 되지 않아 지원해주지 못하는 동작이 많다.(익스폴로어)

---

REST API란?

RESPT API란 REST의 원리를 따르는 API를 의미합니다.

하지만 REST API를 올바르게 설계하기 위해서는 지켜야 하는 몇가지 규칙이 있으며 해당 규칙을 알아 보겠습니다.

REST API 설계 예시

1. URI는 동사보다는 명사를, 대문자보다는 소문자를 사용하여야 한다.

Bad Example http://khj93.com/Running/
Good Example  http://khj93.com/run/  

2. 마지막에 슬래시 (/)를 포함하지 않는다.

Bad Example http://khj93.com/test/  
Good Example  http://khj93.com/test

3. 언더바 대신 하이폰을 사용한다.

Bad Example http://khj93.com/test_blog
Good Example  http://khj93.com/test-blog  

4. 파일확장자는 URI에 포함하지 않는다.

Bad Example http://khj93.com/photo.jpg  
Good Example  http://khj93.com/photo  

5. 행위를 포함하지 않는다.

Bad Example http://khj93.com/delete-post/1  
Good Example  http://khj93.com/post/1  

RESTful이란?

RESTFUL이란 REST의 원리를 따르는 시스템을 의미합니다. 하지만 REST를 사용했다 하여 모두가 RESTful 한 것은 아닙니다. REST API의 설계 규칙을 올바르게 지킨 시스템을 RESTful하다 말할 수 있으며

모든 CRUD 기능을 POST로 처리 하는 API 혹은 URI 규칙을 올바르게 지키지 않은 API는 REST API의 설계 규칙을 올바르게 지키지 못한 시스템은 REST API를 사용하였지만 RESTful 하지 못한 시스템이라고 할 수 있습니다.

REST API의 핵심

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

• 리소스 명은 동사가 아닌 명사를 사용해야 한다.

/students/1

• 리소스는 Collection과 Document로 표현할 수 있다.

이 때 Collection은 복수를 사용함을 주의하자.

/locations/seoul/schools/3

여기서 locations 는 Collection을, seoul 은 Document를 표현한다.

그 리소스에 대한 행위는 HTTP의 Method로 표현해야 한다.

• GET은 리소스를 조회한다. (학생 목록 조회)

GET /students

• POST는 리소스를 생성한다. (학생 생성)

POST /students

• PUT은 리소스를 업데이트한다. (1번 학생 정보 업데이트)

PUT /students/1

• DELETE는 리소스를 삭제한다. (1번 학생 삭제)

DELETE /students/1

HTTP 상태코드

요청에 대한 응답의 상태코드 또한 명확하게 돌려주는 것이 잘 설계된 REST API이다.

• 2xx : 성공 관련 (200 Ok, 201 Created)
• 3xx : 리다이렉션 관련 (304 Not Modified)
• 4xx : 클라이언트 에러 관련 (400 Bad Request, 401 Unauthorized)
• 5xx : 서버 에러 관련 (500 Internal Server Error)

잘못된 REST 사용

• GET/POST의 부적합한 사용 : 기존의 조회/생성의 기능이 아닌 다른 방식으로 사용하는 경우이다.
• 자체 표현적이지 않음 : REST의 특징 중 하나인 자체표현성에서 떨어지는 경우로 이해하기 어렵다.
• HTTP 응답 코드 미사용 : 위에서 정리한 응답에 관한 상태코드를 명확하게 정의하지 않은 경우이다.
• 그 외에 리소스 표현 가이드 및 REST의 특징을 위반한 경우들을 주의하자.

마지막으로 아래 그림을 보고 정리해보자.