RESTful의 대한 기초적인 개념

RESTful이란?
Representational State Transfer라는 용어의 약자로서 웹의 장점을 최대한 활용할 수 있는 아키텍처
최근 서버 프로그램은 다양한 브라우저와 안드로이드폰, 아이폰과 같은 모바일 디바이스에서도 통신을 할 수 있어야한다.

REST가 필요한 이유
-거대한 애플리케이션을 모듈, 기능별로 분리하기 쉬워졌다. RESTful API를 서비스하기만 하면 어떤 다른 모듈 또는 애플리케이션 이라도 RESTful API를 통해 상호간에 통신을 할 수 있기 때문이다.
-WEB브라우저 외의 클라이언트를 위해서다. (멀티 플랫폼)

REST의 특징
1. Uniform (유니폼 인터페이스)
 - 유니폼 인터페이스는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일

2. Stateless (무상태성)
 - 상태가 있다 없다는 의미는 사용자나 클라이언트의 컨텍스트를 서버쪽에 유지하지 않는다는 의미한다.
 - 세션이나 쿠키등을 별도로 관리하지 않기 때문에 API 서버는 요청만을 들어오는 메시지로만 처리하기 때문에 구현이 단순

3. Cacheable (캐시처리가능)
 - REST의 가장 큰 특징중 하나는 HTTP라는 기존 웹 표준을 그대로 사용한다.
 - HTTP가 가진 캐싱 기능이 적용 가능하다. 

 - HTTP 프로토콜 표준에서 사용하는 Last-Modified태그나 E-Tag를 이용하면 캐싱 구현이 가능

4. Self-descriptiveness (자체 표현 구조)
 - REST의 또 다른 큰 특징 중 하나는 REST API 메시지만 보고도 이를 쉽게 이해할 수 있는 자체 표현구조로 되어 있다

5. Clinet - Server Architecture (클라이언트 - 서버 구조)
 - REST 서버는 API를 제공하고, 제공된 API를 이용해서 비즈니스 로직 처리 및 저장을 책임진다.
 - 클라이언트의 경우 사용자 인증이나 컨텍스트(세션, 로그인)등을 직접 관리하고 책임진다.
 - 서로간의 의존성이 줄어들게 된다.

REST구성
- 자원(Resourec) -> URI
- 행위(Verb) -> HTTP Method(GET, PUT, POST, DELETE등등)
- 표현(Representations)

REST API 중심 규칙
- HTTP Method의 행위가 URI 표현으로 들어가면 안된다. (insert, delete...)
- HTTP Method로 CRUD를 할 수 있다.

Create --> Post
Read   --> Get
Update --> Put/Patch
Delete  --> Delete

URI 설계 시 주의할 점
- 소문자를 되도록이면 사용하자, Test와 test는 다른 자원으로 인식한다.
- 하이픈(-)은 URI 가독성을 높이는데 사용하자, 띄어쓰기 대체용
- 확장자를 사용하지말자

자원을 표현하는 Collection과 Document
-도큐먼트는 단순한 문서와 같은 존재, 컬렉션 문서들의 집합, 객체들의 집합같은 존재

리소스는 Collection, Member로 나뉠 수 있다.

Collection -> Read(List), Create

Member -> Read(Detail), Update, Delete

Rest API 설계
1. 복수 명사를 사용하자.
잘못된    예) http://도메인:포트/api/getCoffees
바람직한 예) http://도메인:포트/api/coffees

2. 불필요한 파라미터를 URI Path에 추가하지 말자.
예를 들어 커피 메뉴 리스트중 우유가 추가된 메뉴만 조회할 때 아래처럼 구성한다면 잘못된 예다.
http://도메인:포트/api/coffees/milk

불필요한 파라미터를 추가할 필요는 없다. 아래와 같이 path가 아닌 query param으로 적용하자.

http://도메인:포트/api/coffees?type=milk

 

3. 전역검색과 지역검색

검색은 일반적으로 HTTP GET에서 쿼리스트링에 검색 조건을 정의하는 경우가 일반적인데, 이 경우 검색조건이 다른 쿼리 스트링과 섞여 버릴 수 있다. 예를 들어 name = cho이고 region = seoul인 사용자를 검색하는 쿼리스트링만 사용하게 되면 다음과 같이 표현이 가능하다.

/users?name=cho&region=seoul 

그런데 여기에 페이징 처리를 추가하게 되면 

/users?name=cho&region=seoul&offset=20&limit=10

페이징 처리에 정의된 offset과 limit가 검색조건인지 아니면 페이징 조건인지 분간이 안간다. 그래서 쿼리 조건은 하나의 쿼리스트링으로 정의하는 것이 좋다. 

/users?q=name=cho,region=seoul&offset=20&limit=10

이런식으로 검색 조건을 URLEncode를 써서 q=name=cho, region=seoul 처럼 표현하고 Deleminator를 , 등을 사용하게 되면 검색 조건은 다른 쿼리스트링과 분리된다.

 

HTTP 응답 상태코드

상태 코드	설명
200	클라이언트의 요청을 정상적으로 수행.
201	클라이언트가 어떠한 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨. (POST를 통한 리소스 생성 작업 시)

상태코드	설명
400	클라이언트의 요청이 부적절 할 경우.
401	클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때. (로그인 안한 유저가 로그인을 해야 가능한 리소스를 요청했을 때)
403	유저 인증상태와 관계 없이 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때.
404	존재하지 않는 페이지를 요청했을 때.
409	요청이 현재 서버의 상태와 충돌될 때.
410	요청한 콘텐츠가 서버에서 영구적으로 삭제되었으며, 전달해줄 수 있는 주소 역시 존재하지 않음.
412	클라이언트 헤더에 있는 전제조건은 서버의 전제조건에 적절하지 않을 때.

상태코드	설명
301	클라이언트가 요청한 리소스에 대한 URI가 변경되었을 때 사용.
304	클라이언트에게 응답이 수정되지 않았음을 알려준다.
500	서버의 문제가 생겼을 경우, 개발자의 오류처리가 미흡할 때 생긴다.