REST가 뭔데 그거 어떻게 하는건데(REST와 REST API, 그리고 Open API)

이예빈·2022년 8월 5일
1

HTTP

목록 보기
1/1
post-thumbnail

REST(Representational State Transfer)에 대해 알아보자.

REST가 뭔데


REST는 HTTP의 장점을 최대한 활용할 수 있도록 제안된 아키텍처 원칙으로 로이 필딩(Roy Fielding)이라는 박사의 논문에서 최초로 소개되었다. 이러한 원칙을 준수하여 설계한 API를 REST API 또는 RESTful API라고 한다.

쉽게 말하면 'HTTP를 좀 더 효율적으로 쓰려고 이용하는 시스템 구축 스타일'이라고 할 수 있을 것 같다.

REST가 나타나기 전의 HTTP 세상은 혼돈 그 잡채였다고 한다. 기존에도 여러 방법론들이 존재했지만 그것들을 이용하는 것은 매우 복잡하고 힘들었다. 그래서 로이 선생님이 혀를 쯧쯧차며 REST를 세상에 내놓게 되었다.


그거 어떻게 하는건데


찾아보니 REST API를 작성하려면 어떻게 해야 한다는 복잡한 설명들이 많았다. (하...)
그 중 한 가지인 리차드슨 성숙도 모델(Richardson Maturity Model, RMM)을 가지고 이야기 해보고자 한다. 이름에서도 알 수 있듯이 리차드슨 선생님이 만든 개념인데 이 모델의 4가지 단계(0단계 ~ 3단계)를 모두 충족해야 진정한 REST API라고 할 수 있다는 것이다. (1단계가 아니라 0단계부터 시작한다니...그는 찐이다.)

RMM 0단계: HTTP 사용하기

REST API를 작성하기 위한 RMM 0단계는 당연한 얘기지만 HTTP 프로토콜 사용하기이다.
개똥이가 안쌤 진료 예약을 예시로 HTTP Message를 구성해보면 다음과 같다.

👩🏻‍💻HTTP Request 1

POST /appointmentService HTTP/1.1
[various other headers]

<openSlotRequest date = "2022-08-05" doctor = "안쌤"/>

👩🏻‍⚕️HTTP Response 1

HTTP/1.1 200 OK
[various headers]

<openSlotList>
  <slot start = "1400" end = "1450">
    <doctor id = "안쌤"/>
  </slot>
  <slot start = "1600" end = "1650">
    <doctor id = "안쌤"/>
  </slot>
</openSlotList>

👩🏻‍💻HTTP Request 2

POST /appointmentService HTTP/1.1
[various other headers]

<appointmentRequest>
  <slot doctor = "안쌤" start = "1400" end = "1450"/>
  <patient id = "개똥이"/>
</appointmentRequest>

👩🏻‍⚕️HTTP Response 2

HTTP/1.1 200 OK
[various headers]

<appointment>
  <slot doctor = "안쌤" start = "1400" end = "1450"/>
  <patient id = "개똥이"/>
</appointment>

위의 예시는 HTTP를 사용하였고 요청의 엔드포인트(Endpoint)가 /appointmentService로 동일하게 사용되었다.


RMM 1단계: 리소스를 HTTP URI로 표현하기

RMM 1단계에서는 요청하는 정보(리소스)가 무엇인지에 따라 다른 엔드포인트로 구분하여 사용한다.

👩🏻‍💻HTTP Request 1

POST /doctors/안쌤 HTTP/1.1
[various other headers]

<openSlotRequest date = "2022-08-05"/>

위의 Request는 안쌤의 스케줄 리소스를 요청하는 것이기 때문에 엔드포인트는 doctors/안쌤이다.

👩🏻‍⚕️HTTP Response 1

HTTP/1.1 200 OK
[various headers]

<openSlotList>
  <slot id = "1234" doctor = "안쌤" start = "1400" end = "1450"/>
  <slot id = "5678" doctor = "안쌤" start = "1600" end = "1650"/>
</openSlotList>

👩🏻‍💻HTTP Request 2

POST /slots/1234 HTTP/1.1
[various other headers]

<appointmentRequest>
  <patient id = "개똥이"/>
</appointmentRequest>

위의 Request는 slot id 1234라는 특정 시간에 예약을 요청하는 것이기 때문에 엔드포인트는 slots/1234이다.

👩🏻‍⚕️HTTP Response 2

HTTP/1.1 200 OK
[various headers]

<appointment>
  <slot id = "1234" doctor = "안쌤" start = "1400" end = "1450"/>
  <patient id = "개똥이"/>
</appointment>

위의 예시들에서는 CRUD와 상관 없이 요청에 POST 메서드를 사용하였다.


RMM 2단계: HTTP 메서드 사용하기

RMM 2단계에서는 CRUD에 맞게 적절한 HTTP 메서드를 사용한다.
진료 스케쥴을 요청하는 것은 READ에 해당하고, 특정 시간에 예약을 하는 것은 예약 생성이기 때문에 CREATE에 해당한다.

👩🏻‍💻HTTP Request 1

GET /doctors/안쌤/slots?date=20220805&status=open HTTP/1.1

👩🏻‍⚕️HTTP Response 1

HTTP/1.1 200 OK
[various headers]

<openSlotList>
  <slot id = "1234" doctor = "안쌤" start = "1400" end = "1450"/>
  <slot id = "5678" doctor = "안쌤" start = "1600" end = "1650"/>
</openSlotList>

👩🏻‍💻HTTP Request 2

POST /slots/1234 HTTP/1.1
[various other headers]

<appointmentRequest>
  <patient id = "개똥이"/>
</appointmentRequest>

👩🏻‍⚕️HTTP Response 2

HTTP/1.1 201 Created
Location: slots/1234/appointment
[various headers]

<appointment>
  <slot id = "1234" doctor = "안쌤" start = "1400" end = "1450"/>
  <patient id = "개똥이"/>
</appointment>

HTTP 메서드 사용 규칙

  • GET (READ): 서버의 데이터를 변화시키지 않는 요청에 사용
  • POST (CREATE): 요청마다 새로운 리소스 생성 (안 멱등하다...)
  • PUT (UPDATE): 요청마다 같은 리소스 반환(멱등하다 멱등해...) - 데이터 교체
  • PATCH (UPDATE): 데이터 수정
  • DELETE (DELETE): 딜리트 그 잡채

일반적으로 2단계까지만 해도 REST API라고 하는 경우가 많으며 HTTP API와 REST API를 거의 동일한 용어로 사용하기도 하지만 엄밀히 따지면 REST API는 RMM 3단계까지 모두 충족해야 한다.

위의 HTTP 메서드 사용 규칙에 멱등하다는 말이 있는데
도대체 뭔말이냐면

똑같은 요청을 한번 보내든 여러번 보내든 똑같은 효과라는 뜻이다.


RMM 3단계: HATEOAS,하이퍼미디어 컨트롤 적용하기

하테오아스, 헤이트오아스 아니고 헤이티오스라고 읽는다😎
RMM 3단계에서는 HATEOAS(Hypertext As The Engine Of Application State), 즉 하이퍼미디어 컨트롤을 적용한다.

뭔말이냐면

응답에 링크 요소로 클라이언트가 응답받은 이후에 할 수 있는 액션을 위한 하이퍼 링크를 삽입하는 것이다.

👩🏻‍💻HTTP Request 1 - (2단계의 Request 1과 같다)

GET /doctors/안쌤/slots?date=20220805&status=open HTTP/1.1

👩🏻‍⚕️HTTP Response 1

HTTP/1.1 200 OK
[various headers]

<openSlotList>
  <slot id = "1234" doctor = "안쌤" start = "1400" end = "1450">
     <link rel = "/linkrels/slot/book" 
           uri = "/slots/1234"/>
  </slot>
  <slot id = "5678" doctor = "안쌤" start = "1600" end = "1650">
     <link rel = "/linkrels/slot/book" 
           uri = "/slots/5678"/>
  </slot>
</openSlotList>

응답에 각 스케줄마다 예약하는 링크가 추가되었다.

👩🏻‍💻HTTP Request 2 - (2단계의 Request 2과 같다)

POST /slots/1234 HTTP/1.1
[various other headers]

<appointmentRequest>
  <patient id = "개똥이"/>
</appointmentRequest>

👩🏻‍⚕️HTTP Response 2

HTTP/1.1 201 Created
[various headers]

<appointment>
  <slot id = "1234" doctor = "안쌤" start = "1400" end = "1450"/>
  <patient id = "개똥이"/>
  <link rel = "/linkrels/appointment/cancel"
        uri = "/slots/1234/appointment"/>
  <link rel = "/linkrels/appointment/addTest"
        uri = "/slots/1234/appointment/tests"/>
  <link rel = "self"
        uri = "/slots/1234/appointment"/>
  <link rel = "/linkrels/appointment/changeTime"
        uri = "/doctors/mjones/slots?date=202208054&status=open"/>
  <link rel = "/linkrels/appointment/updateContactInfo"
        uri = "/patients/jsmith/contactInfo"/>
  <link rel = "/linkrels/help"
        uri = "/help/appointment"/>
</appointment>

응답에 예약을 취소하고 변경하고 정보를 확인하는 등의 여러가지 링크가 추가되었다.

Open API


Open API는 말 그대로 열려있는 API라는 뜻이다.

국경없는 멋진 개발자들이 API를 만들어서 공짜로 무한대로 푸는 것은 아니고
걍 일반적으로 IT기업들이 서비스를 (제한적으로) 개방해서 그를 응용한 다양한 서비스들이 생겨나게 하여 자기네들 회사의 비즈니스 확대와 수익 창출의 기회로 이용하는 것이다. 어쨌든 사용하는 입장에서는 땡큐가 아닐 수 없다.

IT기업 뿐 아니라 정부에서 제공하는 날씨정보같은 공공데이터도 Open API형태로 제공되고 있다.

Open API의 예시로 넥슨 카트라이더에서 제공하는 Open API를 가져와봤다.
닉네임을 입력하면 유저의 정보를 받을 수 있는 API이다.
내 닉네임 왜구타파를 입력해서 22레벨의 쪼렙 유저라는 정보를 얻어왔다.

API Key


API를 이용하기 위해서는 대부분 API Key가 필요하다.
API 제공자는 로그인한 이용자에게 자원에 접근할 수 있는 권한을 API Key의 형태로 제공하며, 이용자가 데이터 요청시 API Key를 같이 전달해야 원하는 응답을 받을 수 있다.

나도 위의 Open API를 이용하기 위해서 API Key를 부여받았다.

참고


https://www.joinc.co.kr/w/man/12/rest/about
https://martinfowler.com/articles/richardsonMaturityModel.html
https://blog.restcase.com/4-maturity-levels-of-rest-api-design/
https://developer.mozilla.org/ko/docs/Glossary/Idempotent
https://developers.nexon.com/kart/api/12/33

profile
temporary potato

2개의 댓글

comment-user-thumbnail
2023년 4월 18일

양질의 포스팅 감사합니다

답글 달기
comment-user-thumbnail
2024년 3월 13일

Exploring the world of online gaming sites has been an exhilarating journey filled with excitement and intrigue. With a plethora of games available, ranging from classic casino favorites to immersive multiplayer experiences, there's always something new to discover. Whether I'm embarking on epic quests in fantasy realms or testing my luck in thrilling рейтинг онлайн казино card games, the thrill of the chase is always present. And with the convenience of being able to play from the comfort of my own home, the adventure never has to end. Each gaming session is a chance to escape reality and immerse myself in a world of endless possibilities.

답글 달기