REST API와 HATEOAS

REST API란?

REpresentational State Transfer API(Application Programming Interface)

REST 아키텍처 스타일을 따르는 API

시스템 제각각의 독립적인 진화를 보장하기 위한 방법

Representation 이란?

REST API에서의 "Representation(표현)"은 특정 리소스의 상태를 클라이언트에 전달하기 위해 사용되는 데이터의 형식을 말한다. 클라이언트는 서버로부터 필요한 리소스를 요청하고, 서버는 해당 리소스의 현재 상태를 나타내는 데이터를 클라이언트에게 보내줄 때, 클라이언트가 받는 이 데이터가 바로 "Representation".

REST에서 리소스는 고유한 URL로 식별되며, Representation은 주로 JSON, XML 등의 형식으로 제공된다.
가령, 특정 사용자 정보가 필요할 때 클라이언트가 서버로 /users/123라는 URL을 요청하여 서버는 이 사용자에 대한 JSON 형태의 데이터를 응답으로 보내주면, 이 JSON 데이터가 바로 사용자의 "Representation"인 것.

 

 

https://www.youtube.com/watch?v=RP_f5dMoHFc

 

REST API는 Uniform Interface 를 만족해야 한다.

• self-descrive messages
  
  • 메시지 스스로 메시지에 대한 설명이 가능해야 한다.
  • 서버가 변해서 메시지가 변해도 클라이언트는 그 메시지를 보고 해석이 가능하다.
  • 확장 가능한 커뮤니케이션
• hypermedia as the engine of appliaction state (HATEOAS)
  
  • 클라이언트가 서버가 제공하는 하이퍼미디어 링크와 상호 작용하여 웹 서비스의 리소스를 동적으로 탐색할 수 있도록 하는 REST 아키텍처의 제약 조건
  • 클라이언트가 REST API에 요청하면 서버가 요청된 데이터뿐만 아니라 관련 리소스에 대한 링크(하이퍼미디어)로도 응답. 이러한 링크를 통해 클라이언트는 API 구조에 대한 하드 코딩된 지식이 없어도 다음에 수행할 수 있는 작업을 검색할 수 있게 된다.
    
    • Self-descriptive messages : 클라이언트는 서버가 제공하는 링크를 통해 다음에 취할 수 있는 작업을 이해할 수 있다.
    • Dynamic navigation (동적 탐색) : 클라이언트는 API 구조에 대한 사전 지식이 필요하지 않고, 서버는 링크를 통해 클라이언트를 동적으로 안내
    • Discoverability(검색 가능성) : 클라이언트가 응답에 제공된 링크를 통해 탐색하므로 클라이언트를 중단하지 않고 API가 발전할 수 있다. 즉, 링크 정보를 동적으로 바꿀 수 있다. (Versioning 할 필요 없이!)
      
      
    • 응답 예시 - 계좌 정보 조회
      • 잔고가 양수일 때
        

        

        계좌에 대한 정보 뿐 아니라, 이후 클라이언트-서버 간 상호작용할 수 있는 링크 제공

      • 잔고가 음수일 때
        

        

        예금만 가능하도록 link가 동적으로 바뀜

        
        

응답 예시 : 클라이언트는 사용자의 데이터뿐만 아니라 사용자의 주문과 같은 관련 리소스에 대한 링크, 사용자 정보를 업데이트하는 링크도 수신

 

 

 

 

Self-descriptive message 해결 방법 

• 방법 1: 미디어 타입을 정의하고 IANA에 등록하고 그 미디어 타입을 리소스 리턴할 때 Content-Type으로 사용한다.
• 방법 2: profile 링크 헤더를 추가한다.
  
  • 브라우저들이 아직 스팩 지원을 잘 안해
  • 대안으로 HAL의 링크 데이터에 profile 링크 추가

HATEOAS 해결 방법 

• 방법1: 데이터에 링크 제공
• 방법2: 링크 헤더나 Location을 제공
  (Location header: 3xx은 리다이렉션, 201은 요청에 의해 새로 생성된 리소스의 URI)

---

참고 자료 & 이미지 출처
스프링 기반 REST API 개발 (백기선 님)
https://en.wikipedia.org/wiki/HATEOAS

HATEOAS - Wikipedia