[Web] 2. REST/REST API/RESTful

1. REST

• REST란 REpresentational State Transfer의 약자이다.
• 자원을 이름(자원의 표현)으로 구분하여 해당 자원의 상태(정보)를 주고 받는 모든 것을 의미한다.
• 즉, 자원의 표현에 의한 상태전달.
• 월드 와이드 웹(WWW)과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 개발 아키텍처의 한 형식

1) REST 구성

• 자원(Resource) - URI
• 행위(Verb) - HTTP Method;
• 표현(Representation)

2) REST API의 특징

1. Uniform Interface
   • URI로 지정한 리소스에 대한 조작이 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일
   • HTTP 표준 프로토콜에 따르는 모든 플랫폼(모바일, PC..)에서 사용가능함(특정언어에 종속X)
2. Stateless
   • HTTP 프로토콜을 사용하므로 무상태성을 갖는다.
3. Self-descriptiveness
   • REST API 메시지만 보고 쉽게 이해할 수 있는 자체 표현 구조로 되어있음
4. Cacheable
   • HTTP의 기능인 캐싱이 가능하다.
5. Client-Server
   • 자원을 가지고있는 Server와 요청하는 Client로 나누어 진다.
   • 이에 따라 서로 역할이 명확히 구분되며 의존성이 줄어들게 된다.
   • Server : API 제공, 비즈니스 로직 처리 및 저장
   • Client : 사용자인증, Context(세션, 로그인정보) 등을 직접 관리하고 책임진다.
6. Layered-System(계층화)
   • Server는 다중 계층으로 구성될 수 있다.
   • API서버는 순수 비즈니스 로직을 수행하고, 그 앞에 보안, 암호화, 사용자 인증 단계를 추가하여 구조상 유연함을 줄 수 있다.
   • 로드밸런싱, 공유 캐시등을 통해 확장성, 안전성을 높일 수 있다.

 

3) REST API 디자인 가이드

- 핵심 항목

1. URI는 정보의 자원을 표현해야한다.
2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

[1] URI는 정보의 자원을 표현해야 한다.(동사X -> 명사O)

GET  /members/delete/1

위와 같은 URI는 행위에 대한 표현이 포함되어 있어 REST를 제대로 적용하지 못한 예이다.

[2] 자원에 대한 행위는 HTTP Method로 표현

DELETE /members/1

잘못된 표현을 바꾸면 위와같다.

그 외에도

GET /members/1   (조회)
POST /members/2 (추가)

와같은 형식으로 HTTP Method를 활용하여 URI를 표현해야한다.

행위	HTTP Method	역할
Create	POST	POST를 사용해 URI를 요청하면 리소스를 생성한다.
Read	GET	GET를 통해 해당 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져온다.
Update	PUT	해당하는 리소스를 수정한다. 이때 리소스 전체를 대상으로 수정한다.
Delete	DELETE	해당 리소스를 삭제한다.

[3] 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용

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

[5] 하이픈(-)은 가독성을 높이는데 사용한다. (언더바(_)는 사용하지 않는다.)

 

[6] URI 경로에 대문자를 사용하지 않고 소문자를 사용한다.

[7] 파일확장자(.JPG, PNG ...)는 URI에 포함시키지 않는다.

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

위와같이 헤더를 사용하여 표현한다.

[8] 관계 표현

-일반적인 관계

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

- 관계명이 복잡할 경우는 다음과같이 표기한다.

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

 

[8]  Collection과 Document

Document는 단순히 문서, 한 객체로 이해해도 될 것이다. Collection은 Document(객체)들의 집합이라고 생각하면 좋다.

예를들어

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

위에서 soccer와 13는 Document이다. sport, players는 Collection이다. 차이가 보이는가?

soccer와 같은 운동의 집합을 sports라고 하고 13번 선수와같은 레벨의 선수들의 집합을 players라고 하기 때문이다.

더 나아가면 GET메서드를 사용하면 sports를 통해 soccer와 같은 운동들의 리스트를, players를 통해 선수목록을 가져올 수 있도록 설계해야 할 것이다.

 

4) RESTful

• REST API를 제공하는 웹서비스를 RESTful하다고 표현할 수 있다.
• 즉, REST를 REST답게 쓰는것이 RESTful 하다고 말할 수 있다.
• RESTful의 목적
  • 이해하기 쉽고 사용하기 쉬운 REST API
  • 성능향상이 아닌 일관적인 컨벤션을 통한 API 이해 및 호환 증가이다.

 

5) HATEOAS(Hypermedia As The Engine Of Application state)

REST API를 사용하는 클라이언트가전적으로 서버와 동적인 상호작용이 가능하도록 하는 것을 말한다.

클라이언트가 서버로부터 어떤 요청을 할 때, 요청에 필요한(의존되는) URI를 응답에 포함시켜 반환하는 것으로 가능하다.

 

[1] 장점

• 요청 URI가 변경되도 동적으로 생성된 URI를 사용해 클라이언트가 URI 수정에 따른 코드를 변경하지 않아도 된다.
• URI 정보를 통해 들어오는 요청을 예측할 수 있다.
• Resource가 포함된 URI를 보여주기 때문에, Resource에 대한 확신을 얻을 수 있다.

[2] 예

{ 
    "content":"Hello, World!", 
    "_links":{ 
    	"self":{ 
        	"href":"http://localhost:8080/greeting?name=World" 
		}
	}
}

 

참조

https://meetup.toast.com/posts/92
https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html
https://pjh3749.tistory.com/260
https://wallees.wordpress.com/2018/04/19/rest-api-hateoas/