[WEB] REST API란?

REST란?

---

REST API의 등장 배경

REST는 2000년에 로이 필딩(Roy Fielding)의 논문에서 최초로 소개되었다. 로이 필딩은 당시 웹(HTTP)의 우수성에 비해 제대로 사용되지 못하는 모습에 안타까워 웹(HTTP)의 장점을 최대로 활용할 수 있는 아키텍처로 REST를 발표했다고 한다.

(아키텍처 : 애플리케이션을 설계, 제작하는데 사용하는 패턴과 기술의 총칭)

REST의 정의

Representational State Transfer의 약자로 자원을 이름(자원의 표현)으로 구분하여 해당 자원의 상태를 주고받는 모든 것을 의미한다.

즉, REST란
1. HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고,
2. HTTP Method(POST, GET, PUT DELETE 등)를 통해
3. 해당 자원에 대한 CURD Operation을 적용하는 것을 의미한다.

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

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

REST의 구성 요소

REST API는 다음과 같은 요소로 이루어져있다.

1. 자원(Resource) : URI
2. 행위(Verb) : HTTP Method
3. 표현(Representations)

REST의 장단점

장점

• HTTP를 사용하기 때문에 REST API를 위한 별도의 인프라를 구축할 필요가 없다.
• HTTP 표준 프로토콜을 따르는 모든 플랫폼에서 사용이 가능하다.
• 서버와 클라이언트의 역할을 명확하게 분리된다.
• REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있다.

단점

• 명확한 표준이 존재하지 않는다.
• HTTP Method 형태가 제한적이다.
• 구형 브라우저가 아직 제대로 지원해주지 못하는 부분이 존재한다.
  (PUT, DELETE 사용하지 못하는 점, pushState를 지원하지 않는 점 등)

REST가 필요한 이유

• 최근의 서버 프로그램은 다양한 브라우저와 안드로이드, 아이폰과 같은 모바일 디바이스에서도 통신할 수 있어야 한다.
• 이러한 멀티 플랫폼에 대한 지원을 위해 서비스 자원에 대한 아키텍처를 세우고 이용하는 방법을 모색한 결과, REST에 관심을 가지게 되었다.

REST의 특징

1) Uniform-Interface (유니폼 인터페이스)

• URI로 지정한 Resource에 대한 조작을 통일되고 한정적인 인터페이스로 수행한다.
• HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하며, 특정 언어나 기술에 종속되지 않는다.

2) Stateless (무상태성)

• HTTP의 Stateless한 특징을 REST 또한 그대로 가진다.
• 작업을 위한 상태 정보를 따로 저장하고 관리하지 않는다.
• 세션이나 쿠키 정보를 별도로 저장하고 관리하지 않기 때문에 서버는 들어오는 요청만 단순히 처리하면 된다.
• 때문에 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않아 구현이 단순해진다.

3) Cacheable (캐시 처리 가능)

• REST는 HTTP라는 기존 웹 표준을 그대로 사용하므로 웹에서 사용하는 기존 인프라를 그대로 활용이 가능하며, HTTP가 가진 캐싱 기능을 적용할 수 있다.
• 'Last-modified'태크나 'Etag’를 이용하면 캐싱 구현이 가능하다.
• 캐시 사용을 통해 응답시간이 빨라지고 서버의 자원 이용률을 향상시킬 수 있다.

4) Server-Client 구조

• 자원이 있는 쪽이 Server, 자원을 요청하는 쪽이 Client
• REST 서버는 API를 제공하고 비지니스 로직 처리 및 저장을 책임진다.
• Client는 사용자 인증이나 컨텍스트(세션, 로그인 정보) 등을 직접 관리하고 책임진다.
• 각각의 역할이 확실하게 구분되어 서버에서 개발해야 할 내용이 명확해지고 서로 간 의존성이 줄어든다.

5) Layered System (계층형 구조)

• REST API 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조 상의 유연성을 둘 수 있으며, Proxy나 게이트웨이 같은 네트워크 기반의 중간 매체를 사용할 수 있게 한다.

6) Self-descriptiveness (자체 표현 구조)

• REST API 메시지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조로 되어 있다라는 것이다.

REST API

---

REST API란

REST API란 REST를 기반으로 서비스 API를 구현한 것을 말한다.

(API, Application Programming Interface 는 데이터와 기능의 집합을 제공하여 컴퓨터 프로그램 사이의 상호작용을 촉진하며, 서로 정보 교환이 가능하도록 하는 것)

REST API 설계 기본 규칙

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

• 리소스명은 동사보다는 명사를 사용

GET /books/delete/1 (x)

• URI는 자원을 표현하는데 중점을 두어야 하며, 예시처럼 delete 같은 행위에 대한 표현이 들어가서는 안된다.

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

DELETE /books/1 

URI 설계 시 주의할 점

1) 슬래시(/)는 계층 관계를 나타내는 데 사용

http://restapi.example.com/animals/mammals/whales

2) URI 마지막 문자로 슬래시(/)를 포함하지 않는다.

http://restapi.example.com/houses/apartments/ (x)

3) 불가피하게 긴 URI 경로를 사용한다면 하이픈(-)을 사용 (가독성을 위해)

4) 언더바(_)는 사용하지 않는다 (가독성을 위해)

5) URI 경로에는 소문자를 사용 (대소문자에 따라 다른 리소스로 인식하기 때문)

6) 파일 확장자는 URI에 포함시키지 않는다.

• 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않고 Accecpt header를 사용한다.

http://restapi.example.com/members/soccer/345/photo.jpg (x)

GET / members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg

리소스 간의 관계를 표현하는 방법

리소스 간에 연관 관계가 있을 경우 다음과 같은 표현 방법을 사용한다.

• /리소스명/리소스ID/관계가 있는 다른 리소스명

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

• 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있다.

GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)

자원을 표현하는 Collection과 Document

• Document는 문서 또는 하나의 객체
• Colection은 문서들의 집합, 객체들의 집합
• 컬렉션과 도큐먼트 모두 리소스로 표현할 수 있으며 URI에 표현된다.
• 컬렉션은 복수로 사용

http:// restapi.example.com/sports/soccer/players/13

위의 예시에서 sports, players 컬렉션과 soccer, 13(13번 선수)를 의미하는 도큐먼트로 URI가 이루어져있다. 좀 더 직관적이고 이해하기 쉬운 URI를 설계하기 위해 단수, 복수를 지켜준다.

REST API 설계 예시

HTTP 응답 상태 코드

잘 설계된 REST API는 URI 뿐만 아니라 리소스에 대한 응답을 잘 내어주는 것까지 포함되어야 한다. 정확한 응답 상태 코드만으로도 많은 정보를 전달할 수 있기 때문에 상태 코드 값을 명확히 돌려주는 것이 중요하다.

200, OK - 서버가 요청을 성공적으로 처리함
201, Created - 요청이 처리되어 새로운 리소스가 생성됨
204, No Content - 처리를 성공했지만, 클라이언트에게 돌려줄 컨텐츠가 없음 (응답 바디가 없음 예를 들어 DELETE 요청 시 자주 사용)
400, Bad Request - 요청의 구문이 잘못됨
401, Unauthorized - 지정한 리소스에 대한 액세스 권한이 없음
403, Forbidden - 지정한 리소스에 대한 액세스가 금지됨 (401 인증 처리 이외의 사유로 리소스에 대한 액세스가 금지된 경우)
404, Not Found - 지정한 리소스를 찾을 수 없음
409, Conflict - 서버가 요청을 수행하는 중에 충돌이 발생 (예를 들어, 사용자가 변경하려는 닉네임이 이미 서버에서 사용 중인 경우)
500, Internal Server Error - 서버에서 예기치 못한 에러가 발생함

References
https://www.youtube.com/watch?v=7LbylTMlj8M
https://meetup.nhncloud.com/posts/92
https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html
https://hongong.hanbit.co.kr/http-%EC%83%81%ED%83%9C-%EC%BD%94%EB%93%9C-%ED%91%9C-1xx-5xx-%EC%A0%84%EC%B2%B4-%EC%9A%94%EC%95%BD-%EC%A0%95%EB%A6%AC/