REST / REST API

REST ( Representational State Transfer )
。웹 을 설계하는 하나의 아키텍처 스타일
▶ 아키텍처 스타일 : 제약조건의 집합

。REST 제약조건은 총 6개가 존재하며, 이를 모두 준수해야 Restful하다고 할 수 있다.
▶ 제약조건을 통해 큰 장점들이 존재하여 대부분의 웹서비스가 사용하는 웹 아키텍처

。자원을 자원의 표현으로 구분하여 해당 자원의 상태(= 정보)를 주고 받는 모든 행위
▶ 데이터가 요청되는 시점에서 자원의 상태를 JSON을 통해 주고받음

RESTful
。REST API를 제공하는 웹서비스를 지칭하는 용어
▶ 암묵적으로 REST 제약조건을 준수하는 시스템에 RESTful이라는 용어를 사용한다


REST의 핵심개념 : 자원 / 행위 / 표현

• 자원 (Resource) :
  。해당 서버가 관리하는 모든것
  ▶ REST API가 다루는 대상으로서 주로 명사형태로 표현
  ( ex: 문서 , 그림 , 데이터 등 일반적으로 교환하는 모든 정보를 포함하여 자원이라고 한다.)
  
  。URL를 통해 고유하게 식별하여 위치를 지시
  ex ) /users
  
  
• 행위 (Method)
  。자원에 대해 무엇을 수행할 건지 정의
  HTTP Method
  
  
• 표현 ( Representation ) :
  。자원을 어떤 형식으로 주고받을 지를 정의
  ex ) JSON, XML, ....

REST 아키텍처의 장점
。REST는 제약조건을 통해 다음 장점들이 존재하여 대부분의 웹서비스가 사용

• 확장성
  。REST의 Stateless 제약조건을 통해 요청마다 독립적이므로, 서버를 쉽게 Scale-out하여 증설할 수 있다.
  ▶ 로드밸런싱이 쉬운 특징으로 대규모 서비스에 적합
  
  
• 유지보수 용이
  。REST의 Client-Server 제약조건을 통해 프론트엔드와 백엔드가 완전히 분리되어 서로 영향 없이 유지보수가 가능
  
  
• 일관성
  。REST의 Uniform Interface 제약조건을 통해 API 규칙이 통일되어 처음 보는 API도 용이하게 해석가능
  
  
• 캐싱 가능
  。REST의 Cacheable 제약조건을 통해 HTTP Cache를 이용하여 WAS까지 요청할 필요 없이, Cache Server에서 데이터를 쉽게 가져오므로 응답성능 향상
  
  
• 유연한 구조
  。REST의 Layered System 제약조건을 통해 중간에 프록시 서버 / 로드 밸런서 등을 추가해도 클라이언트는 서버와 통신 시 어떤 중간 계층을 거치는지 알 수 없음

REST 아키텍처 제약 조건
。REST 제약조건은 총 6개가 존재하며, 이를 모두 준수해야 Restful하다고 할 수 있다.
▶ Client-Server / Stateless / Cacheable / Layered System / Uniform Interface / Code-On-Demand

。HTTP만 잘 지키더라도 Client-Server, Stateless, Cache, Layered System을 모두 준수
▶ HTTP 프로토콜을 사용하는 상태에서 REST API 설계 시 Uniform Inteface만 중점적으로 고려

• Client-Server
  。REST 아키텍처는 클라이언트 / 서버로 분리되어야한다.
  ▶ 。HTTP 프로토콜을 사용하는 구조 자체가 Client - Server Architecture 이므로 준수
  
  
• Stateless
  。REST 아키텍처는 이전 요청을 기억하지 않아야한다.
  ▶ HTTP 프로토콜은 STATELESS 특징으로 서버에서 클라이언트에 대한 정보를 알 수 없으므로 준수
  
  
• Cacheable
  。REST 아키텍처는 응답을 캐싱할 수 있어야한다.
  ▶ HTTP는 Web Cache를 사용하여 브라우저에 빠른 응답을 지원
  
  
• Layered System
  。REST 아키텍처는 중간에 프록시 / 로드밸런서 등이 존재할 수 있어야 한다.
  
  。 HTTP는 클라이언트와 서버 사이에 프록시서버 ( 웹캐시 ) , API 게이트웨이 등 다양한 중간 계층들 간에 서로 기능별로 독립되어 분리
  ▶ 계층의 유지보수 시 다른 계층에 영향을 주지않음.
  ▶ 클라이언트는 서버와 통신 시 어떤 중간 계층을 거치는지 알 수 없음
  
  
• Code-on-Demand ( 선택 )
  。REST 아키텍처는 서버에서 코드를 클라이언트로 전송하여 실행할 수 있도록 한다.
  ▶ 이는 JS를 의미하며 꼭 준수할 필요는 없음.
  
  
• Uniform Interface
  。REST 아키텍처는 클라이언트가 서버 내 자원에 접근하는 방식이 일관되도록 해야한다.
  ▶ REST API 설계 시 가장 신경 쓸 부분

Uniform Interface
。클라이언트가 서버 내 자원에 접근하는 방식이 일관되도록 하도록 하는 것
▶ 서버 내 다른 자원에 접근하더라도 항상 동일한 Type ( Http Method, URI 구조, Response Format )으로 접근이 가능하도록 하는 것

• Identification of Resource
  。서버 내 모든 자원은 고유한 URL로 식별되어야함
  ▶ 명확한 비즈니스 모델로 설정
  ex ) /users/1, /orders/2 , ...
  
  
• Manipulation of resources through representations
  。클라이언트에서 Representation ( JSON, XML, ... )를 전송하여 서버 내 자원의 조작( CRUD )이 가능한 것
  
  
• Self-Descriptive Message
  。API의 요청과 응답은 외부 문서 없이 스스로 설명할 수 있어야한다.
  ▶ HTTP Message에 표현을 작성하여 추가 문서 없이 HTTP Message 자체만으로 의미를 이해해야할 수 있어야하는 능력

  Self Descriptive한 HTTP Message 예시

  POST /api/index.html HTTP/1.1
  Host: example.com
  Content-Type: application/json-patch+json // Data type 지정
  Content-Length: 45
  { 						 	//	 Http Message Body 부분
    "name": "홍길동",			
    "email": "hong@example.com"
  }

  。목적지 Host : example.com
  。요청할 서버내 자원 : /api/index.html
  。Content-Type 헤더 : application/json-patch+json
  ▶ json-patch 명세를 통해 HTTP Message Body의 변수를 설명
  
  ▶ 다음처럼 작성하여 메시지 내용으로 온전히 해당 메시지를 해석 할 수 있어야한다.

• 
  
  
• HATEOAS
  。REST API는 Hypertext-driven 되어야한다.
  
  。클라이언트에서 REST API를 통해 제공된 다른 자원을 지시하는 하이퍼링크를 통해 어플리케이션의 상태를 전이
  ▶ Http Message의 Link 헤더를 통해 다른 자원에 대한 하이퍼링크를 제공

HTTP/1.1 200 OK
Content-Type: application/json
Link: </articles/1>; rel="previous",
			</articles/3>; rel="next";

REST API
。REST 원칙을 따르는 API
▶ HTTP를 기반으로 하여 REST 제약조건을 준수

。웹에서 다른 프로그램이 자원을 주고받기 위한 표준방식의 통신규칙
▶ 클라이언트와 Web Application 간 자원을 주고받기위한 인터페이스

。 언어 , 프레임워크 , 기술 등에 영향을 받지 않으면서 지정된 데이터 형식( JSON , XML )을 통해 클라이언트와 서버간 데이터 교환이 가능

。HTTP Method를 지원 및 HTTP의 STATELESS 특징을 승계하여 서버는 클라이언트를 알 수 없다.
▶ 매 Request 마다 인증을 요구.
▶ GET, POST, DELETE, PUT, HEAD, PATCH, OPTIONS를 지원

。Spring의 REST API는 Spring MVC에서 @RestController를 통해 Controller로서 구축되어 요청 및 응답이 수행
▶ @ResponseBody 기능 추가

REST API 설계

• REST API는 Hypertext-driven 되어야한다
  。API에 HATEOAS 적용
  ▶ 클라이언트에서 Hyperlink를 통해 어플리케이션의 상태를 변화
  
  
• Resource의 명사 표현 :
  。URL은 Resource이므로 도메인( = 비즈니스 모델 )으로 지칭하며 동사가 아닌 명사들로 구성되어야 한다.
  ▶ REST API 설계 시 단수, 복수형을 섞어 사용하지 않으며, 모든 Resource에 대해 복수형 명사 사용!
  
  
• 자원 검색 시 Path Variable 사용 :
  。Query String의 /getUser?id=1이 아닌 @RestController에 의한 Path Variable의 /users/{id} 가 맞는 표현.
  ▶ 해당 자원에 대해 추가 질의가 존재하는 경우에만 query string을 사용
  
  ex ) URI : https://{serviceRoot}/{collection}/{id}
  
  
• 적절한 Http Status Code를 반환
  。@ResponseStatus 어노테이션을 통해 클라이언트가 요청 후 성공 시 200을 반환하도록 @ResponseBody( code=HttpStatus.OK ) 설정
  
  
• HTTP Method의 적절한 사용하여 REST : 행위를 표현 :
  。REST는 해당 요청의 의도를 쉽게 파악 할 수 있도록 HTTP Method를 목적에 따라 구분하여 사용.
  ▶ POST /users/1/delete가 아닌 DELETE /users/1로 표기.

  HTTP Method 별 Endpoint
  。특정 Resource를 조작하기 위한 URL 패턴
  
  。users는 백엔드 기준 도메인( = 비즈니스 모델 )인 user에서 복수로 표현가능하므로 관례적으로 users로 설정
  
  。GET /api/users : 모든 사용자 조회
  。GET /api/users/{id} : 특정 사용자 조회
  。POST /api/users : 새로운 사용자 생성
  。PUT /api/users/{id} : 특정 사용자 정보 전체 수정
  。PATCH /api/users/{id} : 특정 사용자 정보 일부 수정
  。DELETE /api/users/{id} : 특정 사용자 삭제
  。GET /api/users/{id}/posts : 특정 사용자와 연결된 모든 게시물 검색
  。POST /api/users/{id}/posts : 특정 사용자와 연결된 게시물 생성
  。GET /api/users/{id}/posts/{post_id} : 특정 사용자와 연결된 특정 게시물 검색

출처 - 그런 REST API로 괜찮은가