진짜 RESTful API에 대해서

내게 REST api는 그냥  http 통신 응답 바디에 단순하게 json 객체같은 형태로 데이터를 반환하는 것.

(쉽게 말하자면 그냥 스프링 @RestController 핸들러 메서드에서 객체를 반환하는 것과 같은)

그리고 url을 통해서 리소스를 정의하는 관례들, 그리고 Http method를 이용해서 리소스를 가공하는. 

이런 식으로만 알고 있었다. 

 

하지만 뭔가 위화감이 느껴졌다.  '고작 이런게 REST라고?'

의심하기 시작하니 뭔가 이상한 부분이 느껴졌다. 

URL 관례나 응답 데이터 포맷, Http method에 관한 부분에 대한 부분은 그냥 일반적인 HTTP를 기반으로한 규칙 정도로 느껴졌기 때문이다. 정말 그것 뿐이라면 REST라는 이름을 붙이고 떼어내 아키텍쳐로 분리하기도 민망하지 않은가?

 

내가 모르는 뭔가가 있다. 검색 검색 검색....

 

역시 빠뜨린 부분이 있었다.

https://restfulapi.net/   

What is REST – Learn to create timeless REST APIs

 

REST : REpresentational State Transfer

 

REST 라는 의미를 정말 제대로 이해하려면 하이퍼미디어 라는게 필요하다. 그리고 부수적으로 representation 이라는 개념도.

 

우선 Representation 이라는 단어를 살펴보자. REST 문서에 상당히 많이 등장하는 단어다.

The state of the resource at any particular timestamp is known as resource representation.

특정 어떤 시점의 리소스의 상태라고 한다. json 포맷을 사용한다면 응답 바디의 json 객체들로 봐도 무방하다. 

Representation 의 의미를 굳이 사전에서 찾자면 대표라는 의미보다 표현이나 묘사같은 뉘앙스에 가깝다.

그러니까 representation 은 리소스의 상태를 나타내는 용어지만, 또한 상태를 충분히 잘 묘사하고 있다는 뉘앙스를 내포하는 단어다.

 

왜 representation 라는 단어를 썼을까? 단순히 응답 포맷을 json, xml 포맷으로 바꾼다고 해서 representational 하다고 볼 수는 없다. json, xml 과 같은 포맷은 전혀 새로운 것이 아니었고, 로이 필딩은 뭔가 그 이상의 리소스 상태의 서술을 주문한 것이다.

   

그 이상의 것이 바로  하이퍼미디어(hypermedia) 라고 생각한다.

 

하이퍼미디어라고 해서 뭐 엄청 특별한게 아니다. 하이퍼텍스트와 동일한 개념이다.

포맷에 특정하지 않고 링크를 통해 다른 리소스로 이동하는 것을 하이퍼미디어 라고 하는것 같다.

{
  "_embedded": {
    "employees": [
      {
        "id": 1,
        "name": "Bilbo Baggins",
        "role": "burglar",
        "_links": {
          "self": {
            "href": "https://example.com:9001/employees/1"
          },
          "employees": {
            "href": "https://example.com:9001/employees"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://example.com:9001/employees"
    },
    "root": {
      "href": "https://example.com:9001"
    }
  }
}

 

위 예제는 "/emplyees" 라는 URL을 요청하고 응답으로 받은 JSON 객체다.

 

주목할 부분은 _link 속성이다.

employees 배열 안의 요소를 보자. employ 객체 속성의 값들이 나타나 있고 또 _link 라는 속성이 있다.

self 라는건 관계(link relation)를 나타낸다고 알아두자. 여기서는 자신임을 나타내고 있다. 그리고 self 안에 다시 href 속성이 있고 url이 포함되어 있다. 저 url을 통해서 다시 /employees/1 로 이동할 수 있다.

 

이런 식으로 링크를 통해 데이터를 순회할 수 있다. 마치 웹페이지처럼!

또한 리소스의 제어 url 들을 링크에 추가할 수도 있다. REST api 응답 자체가 하나의 문서가 되는 것이다. 

로이 필딩이 말한 REST는 이런 것이었다고 생각이 든다.

 

REpresentational State Transfer에서 마지막 Transfer는 하이퍼미디어를 통해 이동 가능함을 의미한 것 같다.