Rest API

1. REST API

1.1 REST(Representational State Transfer)란?

• REST란 소프트웨어 프로그램 개발의 아키텍처의 한 형식입니다.
• REST란, "웹에 존재하는 모든 자원(이미지, 동영상, DB 자원)에 고유한 URI를 부여해 활용"하는 것으로, 자원을 정의하고 자원에 대한 주소를 지정하는 방법론을 의미한다고 한다.
• Representational State Transfer -> 자원(resource)의 대표(representation)에 의한 상태 전달

1.1.1 자원 (Resource - URI로 정의)

• '자원'이란 뜻은 넓은 의미로 해당 소프트웨어가 관리하는 모든 것. (Ex. 문서, 그림, 데이터,소프트웨어 자체)
• 예를 들어 DB에 학생 명부가 저장되어 있다고 한다면 이 학생들의 정보가 자원이 됩니다.

1.1.2 대표 (representation)

• '자원의 대표'의 의미는 그 자원을 대표하기 위한 이름을 뜻합니다. (Ex. Students)

1.1.3 상태 전달

• 데이터가 요청되어지는 시점에서 자원의 상태(정보)를 전달하는 것을 뜻합니다.
• 데이터를 요청하는 시점에 따라 데이터가 바뀔 수도 있기 때문에 '상태'라는 표현을 쓴 것
• 프로그램이 학생 명부 전체 리스트를 요청받으면 해당 시점의 '상태' 즉 데이터를 전달하게 됩니다.

• 자원을 이름으로 구분하고, 해당 자원의 상태를 주고 받는 모든 것이 REST라고 할 수 있지만, 일반적으로 REST라고 하면 좁은 의미로 HTTP를 통해 어떤 자원에 대해서 CRUD를 실행하는 방식을 뜻합니다.
• JSON 혹은 XML를 통해 데이터를 주고 받는 것이 일반적입니다.

1.2 REST API

1.2.1 REST API 구성

• Resource
  서버는 Unique한 ID를 가지는 Resource를 가지고 있으며, 클라이언트는 이러한 Resource에 요청을 보냅니다. 이러한 Resource는 URI에 해당합니다.
  
• Method
  서버에 요청을 보내기 위한 방식으로 GET, POST, PUT, PATCH, DELETE가 있습니다. CRUD 연산 중에서 처리를 위한 연산에 맞는 Method를 사용하여 서버에 요청을 보내야 합니다.
  
• Representation of Resource
  클라이언트와 서버가 데이터를 주고받는 형태로 json, xml, text, rss 등이 있습니다. 최근에는 Key, Value를 활용하는 json을 주로 사용합니다.

1.2.2 REST의 특징

1. Uniform Interface(일관된 인터페이스)
   Uniform Interface란, Resource(URI)에 대한 요청을 통일되고, 한정적으로 수행하는 아키텍처 스타일을 의미합니다. 이것은 요청을 하는 Client가 플랫폼(Android, Ios, Jsp 등) 에 무관하며, 특정 언어나 기술에 종속받지 않는 특징을 의미합니다. 이러한 특징 덕분에 Rest API는 HTTP를 사용하는 모든 플랫폼에서 요청가능하며, Loosely Coupling(느슨한 결함) 형태를 갖게 되었습니다.
   
2. Stateless(무상태성)
   서버는 각각의 요청을 별개의 것으로 인식하고 처리해야하며, 이전 요청이 다음 요청에 연관되어서는 안됩니다. 그래서 Rest API는 세션정보나 쿠키정보를 활용하여 작업을 위한 상태정보를 저장 및 관리하지 않습니다. 이러한 무상태성때문에 Rest API는 서비스의 자유도가 높으며, 서버에서 불필요한 정보를 관리하지 않으므로 구현이 단순합니다. 이러한 무상태성은 서버의 처리방식에 일관성을 부여하고, 서버의 부담을 줄이기 위함입니다.
   

3. Cacheable(캐시 가능)
   Rest API는 결국 HTTP라는 기존의 웹표준을 그대로 사용하기 때문에, 웹의 기존 인프라를 그대로 활용할 수 있습니다. 그러므로 Rest API에서도 캐싱 기능을 적용할 수 있는데, HTTP 프로토콜 표준에서 사용하는 Last-Modified Tag 또는 E-Tag를 이용하여 캐싱을 구현할 수 있고, 이것은 대량의 요청을 효울척으로 처리할 수 있게 도와줍니다.
   

4. Client-Server Architecture (서버-클라이언트 구조)
   Rest API에서 자원을 가지고 있는 쪽이 서버, 자원을 요청하는 쪽이 클라이언트에 해당합니다. 서버는 API를 제공하며, 클라이언트는 사용자 인증, Context(세션, 로그인 정보) 등을 직접 관리하는 등 역할을 확실히 구분시킴으로써 서로 간의 의존성을 줄입니다.
   

5. Self-Descriptiveness(자체 표현)
   Rest API는 요청 메세지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조로 되어있습니다. 아래와 같은 JSON 형태의 Rest 메세지는 http://localhost:8080/board 로 게시글의 제목, 내용을 전달하고 있음을 손쉽게 이해할 수 있습니다. 또한 board라는 데이터를 추가(POST)하는 요청임을 파악할 수 있습니다.

HTTP POST , http://localhost:8080/board
{
	"board":{
		"title":"제목",
		"content":"내용"
	}
}

6. Layered System(계층 구조)
   Rest API의 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 등을 위한 계층을 추가하여 구조를 변경할 수 있습니다. 또한 Proxy, Gateway와 같은 네트워크 기반의 중간매체를 사용할 수 있게 해줍니다. 하지만 클라이언트는 서버와 직접 통신하는지, 중간 서버와 통신하는지 알 수 없습니다.

1.2.3 REST API의 설계 가이드

• 리소스에 대한 행위는 HTTP Method(GET, POST, PUT, PATCH, DELETE 등)로 표현해야 합니다.

• /(슬래시)는 계층 관계를 나타낼때 사용합니다.

• URI 마지막 문자에 /(슬래시)를 사용하지 않습니다.

• URI에 _(underscore)는 사용하지 않도록 합니다. 또한 영어 대문자보다는 소문자를 씁니다.
  그리고 가독성을 위해서 긴 단어는 잘 사용하지 않습니다.

• URI에 동사는 GET, POST와 같은 HTTP Method를 표현하기 때문에 동사가 아니라 명사를 사용한다.

• URI에 파일의 확장자(예를들어 .json , .JPEG)를 포함 시키지 않습니다.

1.2.4 RESTful

• RESTful은 REST의 설계 가이드

• REST는 위 정의들을 구현하는 방식에 제약을 두지 않기 때문에 구체적인 가이드라인이 없습니다.

• REST API 설계 가이드에 따라 API를 만들어서 웹 서비스를 제공하면 해당 웹 서비스는 RESTful하다고 합니다.

• API를 RESTful 하게 만들어서 API의 목적이 무엇인지 명확하게 하기 위해 RESTful 함을 지향 합니다.

1.2.5 REST API 성숙도 모델

• 자원 : Resource (URI)
• 행위 : Http Method (GET, POST 등)
• 표현 : 자원의 형태 - JSON, XML 등

Level 0 : 1 URI, 1 HTTP method
-> 하나의 POST Method로 함수이름과 인자를 넘김
-> 전달되는 서로 다른 매개변수를 통해서 하나의 endpoint로 여러 동작을 하게 된다.
-> 매개변수를 Body 로 전달하기 위해 HTTP method 는 POST 가 된다.

Level 1 : N URI, 2 HTTP method
-> Resource 별로 고유한 URI를 사용해서 식별하는 것이다.
-> URI에 /create, /update 등 표현

Level 2 : N URI, 4 HTTP method
-> URI 에 action 이 담기지 않는다.
-> 멱등성(같은 결과를 출력하는 것)을 보장하는 GET 에는 Cache 가 적용되며
-> Response 에 HTTP Status Code 가 의미있게 반환된다.

Level 3 : Hypermedia As Engine of Application State
-> API 서비스의 모든 endpoint 를 최초 진입점이 되는 URI 를 통해 Hypertext Link 형태로 제공
-> 어떤 request 의 다음 request 에 필요한 endpoint 를 제공한다는 것

Level 4 : API Versionning (어떤 단계에서도 적용 가능)
-> URI 버전 방식
-> Request Param 버전 방식
-> Header 버전 방식
-> Media Type 버전 방식

@GetMapping(path = "/users/{id}/v1") // -> URI 활용
@GetMapping(value="/users/{id}/", params = "version=1") -> param 활용
@GetMapping(value = "/users/{id}", headers = "X-API-VERSION=1") -> header 활용
@GetMapping(value = "/users/{id}", produces = "application/vnd.company.appv1+json") // media type versioning

---

1.3 REST 서비스 사용하기

• RestTemplate : 스프링 프레임워크에서 제공하는 간단하고 동기화된 REST 클라이언트

• Traverson : 스프링 HATEOAS에서 제공하는 하이퍼링크를 인식하는 동기화 REST 클라이언트로 같은 이름의 자바스크립트 라이브러리로 비롯된 것

• WebClient : 스프링 5에서 소개된 반응형 비동기 REST 클라이언트

1.3.1 RestTemplate

• RestTemplate은 REST 리소스를 사용하는 데 번잡한 일을 처리해준다.

RestTemplate restTemplate = new RestTemplate();

@Bean
public RestTemplate restTemplate() {
	return new RestTemplate();
}

• 리소스 가져오기 (GET)

public Ingredient getIngredientById(String id) {
    return restTemplate.getForObject(
          "http://localhost:8080/ingredients/{id}", Ingredient.class, id);
}
        
public Ingredient getIngredientById(String id) {
     Map<String, String> urlVariables = new HashMap<>();
     urlVariables.put("id", id);
     
     return restTemplate.getForObject(
            "http://localhost:8080/ingredients/{id}", Ingredient.class, urlVariables);             
}    

public ResponseEntity<Ingredient> getIngredientById(String id) {
	// headers, body, status 정보 포함
    return restTemplate.getForEntity(
          "http://localhost:8080/ingredients/{id}", Ingredient.class, id);
}
        

• 리소스 데이터 추가하기 (POST)

public Ingredient createIngredient(Ingredient ingredient) {
	return restTemplate.postForObject(
    "http://localhost:8080/ingredients", ingredient, Ingredient.class);
}

public ResponseEntity<Ingredient> createIngredient(Ingredient ingredient) {
  // headers, body, status 정보 포함
    return restTemplate.postForEntity(
    "http://localhost:8080/ingredients", ingredient, Ingredient.class);
}

• 리소스 수정 (PUT)

public void updateIngredient(Ingredient ingredient) {
	restTemplate.put(
          "http://localhost:8080/ingredients/{id}", Ingredient.class, ingredient.getId());
}

• 리소스 삭제 (DELETE)

public void deleteIngredient(Ingredient ingredient) {
	restTemplate.delete(
          "http://localhost:8080/ingredients/{id}", ingredient.getId());

• restTemplate.exchange

ResponseEntity<List<Ingredient>> ingredients = restTemplate.exchange(getUrl
, HttpMethod.GET, null, new ParameterizedTypeReference<List<Ingredient>>() {
                });
                
 RequestEntity<Taco> requestEntity = RequestEntity
                .post(postUrl)
                .contentType(MediaType.APPLICATION_JSON)
                .body(taco);
                
ResponseEntity<Taco> retTaco = restTemplate.exchange(requestEntity, Taco.class);                

1.3.2 Traverson

• 스프링 데이터 HATEOAS에 같이 제공, 하이퍼미디어 API를 사용할 수 있는 솔루션

	Traverson traverson = new Traverson(URI.create("http://localhost:8080/api")
    , MediaTypes.HAL_JSON);

• Ingredient 목록조회

ParameterizedTypeReference<Resources<Ingredient>> ingredientType =
new ParameterizedTypeReference<Resources<Ingredient>>() {};

/* /api/ingredients */
Resources<Ingredient> ingredientRes = traverson.follow("ingredients").toObject(ingredientType);

Collection<Ingredient> ingredients = ingredientRes.getContent();

• 최근 Taco 목록조회

ParameterizedTypeReference<Resources<Taco>> tacoType =
new ParameterizedTypeReference<Resources<Taco>>() {};

/* /api/tacos/recents */
Resources<Taco> tacoRes = traverson.follow("tacos", "recents").toObject(tacoType);

Collection<Taco> tacos = tacoRes.getContent();

1.3.3 RestTemplate vs Traverson

• RestTemplate은 리소스를 쓰거나 삭제할 수 있지만, API를 이동하는 것은 쉽지 않다.

• Traverson은 HATEOAS가 활성화된 API를 이동하면서 해당 API 리소스를 쉽게 가져올 수 있지만, 리소스를 쓰거나 삭제하는 메소드를 제공하지 않는다.

• 따라서, API 이동과 변경 삭제를 모두 해야 한다면 2가지를 함께 사용해야 한다.

private Ingredient addIngredient(Ingredient ingredient) {

	/* /api/ingredients */
	String url = traverson.follow("ingredients").asLink().getHref();
	
    	return restTeamplate.postForObject(url, ingredient, Ingredient.class);
}