RESTful API와 REST 성숙도 모델

🐕 RESTful API

https://aws.amazon.com/ko/what-is/restful-api/

RESTful API란 무엇인가요? - RESTful API 설명 - AWS

RESTful API에 대해서 aws 사이트는 다음과 같이 정의한다.

두 컴퓨터 시스템이 인터넷을 통해 정보를 안전하게 교환하기 위해 사용하는 인터페이스

SOP 원칙과도 일맥상통하는 것 같은 느낌이 드는데

인터넷을 통해 정보를 교환하는 과정에서 안정성을 보장해주기 위해 사용하는 약속같은 것이라는 의미이다.

항상 신뢰할 수 있는 서버하고만 통신하는 것은 불가능하니 방법을 신뢰성 있게 하면 된다는 해결방식으로 느껴진다.

그런데 REST는 무엇이고 API는 무엇인가? 

---

👻API는...

https://namu.wiki/w/API

나무위키에도 항목이 개설되어 있을 정도로 대중화 되어 있는 소프트웨어 용어 중 하나인 API는

정작 이게 뭘 뜻하냐는 질문에는 선뜻 대답하기 꺼려지는 부분이 있다.

대충 이런거라는 느낌은 있지만 대답을 하기엔 긴가민가하다.

풀네임을 보면 조금 감이 잡히는데 API는 즉 이것이다.

Application Programming Interface

애플리케이션 프로그래밍 인터페이스

애플리케이션은 뭐고 인터페이스는 뭐고 이런식으로 쭉 내려가다보면 끝이 없으니

이정도쯤에서 멈추는 것이 좋을 것 같다.

간단하게 생각하면 프로그래밍을 할 때 지키자고 약속 / 합의한 규칙이라고 생각하면

약간의 곡해가 있지만 쉽게 와닿는 표현이 된다.

---

🥶 REST는...

Representational State Transfer(REST)

대충 직역하면 상태를 옮기는 것을... 대표하는... 정도로 해석할 수 있을 것 같다.

이 REST는 Roy Fielding이란 사람이 자신의 박사 학위 논문에 정의한

네트워크 소프트웨어 아키텍처이다.

 

즉 네트워크에서 통신을 할 때 지켜야할 설계 규칙 / 구조 규칙 정도로 해석할 수 있다.

구글에 이름을 검색하면 활짝 웃는 사진이 나오신다..

 

---

🌞그럼 다시 돌아가서 RESTful API는?

지금까지 알아본 두 단어의 개념을 통합하여 보면

RESTful API는 이렇게 풀어 쓰는 것도 가능할 수 있다.

네트워크에서 통신을 구성할 때의 방법론 중 하나인 REST라는 지침을 잘 지켜가며 만들어
안전하고 신뢰할 수 있는 통신 규칙 혹은 방식

---

😋REST 성숙도 모델

REST API를 실용적으로 적용하기 위해 레오나르도 리차드슨(Leonard Richardson)이란 사람이 만든

REST 성숙도 모델이라는 것이 존재합니다.

이분도 검색하면 바로 최상단에 검색되시네요

하여간 REST 성숙도 모델은 총 4단계로 구분을 할 수 있고 0 ~ 3단계까지 존재합니다.

엄밀하게 3단계 원칙까지 준수하는 건 어렵기 때문에

주로 2단계 정도까지만 적용하는 것으로 타협한다고 하네요

---

🤢REST 성숙도 모델 0단계 The Swamp of POX

https://www.crummy.com/writing/speaking/2008-QCon/act3.html

JWTUMOIM: Act 3

Leonard Richardson의 위 블로그 게시물을 살펴보면

0단계에 대한 비판이 여실히 드러납니다.

Does this look like the web?
Well, it looks like a part of the web most people hate:
Flash-based websites for restaurants or artists or whatever.

이 수준의 웹은 그저 HTTP 를 사용하는 것만으로도 달성됩니다.

---

🤮REST 성숙도 모델 1단계 Resources

이 레벨에서 지켜져야할 점은 다음과 같습니다.

1. 모든 자원은 개별 리소스에 맞는 엔드포인트를 사용해야할 것

2. 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 할 것

 

엔드포인트라는 말이 생소하게 느껴질 수 있습니다.

RESTful API에서 이야기하는 엔드포인트는 다음과 같습니다. 

엔드포인트는 리소스를 나타내는 URI(Uniform Resource Identifier)와
해당 리소스와 상호 작용하는 데 사용할 수 있는 HTTP 메서드 (GET , POST , PUT , DELETE)입니다. 

GET /books: 모든 도서 목록을 가져옵니다.
GET /books/{id}: 특정 도서를 ID로 조회
POST /books: 새 책을 만듭니다.
PUT /books/{id}: 특정 도서를 ID로 업데이트
DELETE /books/{id}: 특정 도서를 ID로 삭제

이런식으로 말이에요!

이 엔드포인트를 작성할 때 지켜주어야 할 원칙이 있는데

엔드포인트 주소에 동사를 사용하는 것을 자제해야한다는 것입니다.

무슨 일을 할 것인지는 앞의 HTTP 메서드가 이미 표현해주고 있으니까요

예컨대 우린 위 엔드포인트들을 보고 쉽게 의미하는 바를 해석할 수 있습니다.

GET / books 책들을 / 가져오다와 같이요!

 

이외에도 REST API를 설계하면서 고려하면 좋은 엔드포인트 네이밍 원칙들은 

https://www.freecodecamp.org/korean/news/rest-api-mobeom-sarye-rest-endeupointeu-seolgye-yesi/

위 포스트에서 쉽게 찾아볼 수 있습니다.

 

또한 요청에 따른 응답으로 리소스를 전달할 때에도

사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공 / 실패 여부를 반환해야 합니다.

---

🐶REST 성숙도 모델 2단계 HTTP Verbs

성숙도 모델 2단계에서는 CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둡니다.

즉 어떤 리소스를 조회하는 행위를 하고 싶은 경우엔 GET 메서드를 

어떤 리소스를 삭제하는 행위를 하고 싶은 경우엔 DELETE 메서드를 사용하는 등

CRUD 에 맞는 적절한 HTTP 메서드를 통해 요청을 처리하면 됩니다.

 

다만 여기서 조금 헷갈리는 부분이 생기는데 예컨대 아래와 같은 규칙 혹은 주의사항이 있습니다.

1. GET 메서드의 경우 서버의 데이터를 변화시키지 않는 요청에 사용해야합니다.

2. PUT 메서드는 교체를 할 때 PATCH 메서드는 수정을 할 때 사용해야 합니다.

3. PUT 메서드는 멱등성이 보장되는 반면 POST 메서드는 멱등성이 보장되지 않습니다.

4. PATCH 메서드는 멱등성을 보장하지 않을 수도 있습니다.

 

개인적으론 3,4번이 제일 혼란스러운 부분이었는데

https://oen-blog.tistory.com/211

[ RESTful API] PUT과 PATCH의 차이 - 멱동성을 보장하는 PUT, 멱등성을 보장하지 않는 PATCH

4번에 대한 설명은 위 포스트에서 명쾌하게 설명이 되어있으니 참고하시는 걸 추천드립니다.

 

3번으로 돌아와서 3번이 어려운 이유는

우선 멱등성이란 개념을 이해하는 것부터 초심자의 입장에선 쉽지 않을 뿐더러

왜 PUT 메서드는 멱등성이 보장되는가? 에 대한 이해또한 필요하기 때문입니다.

멱등성은 어떤 대상에 같은 연산을 여러번 적용해도 결과가 달라지지 않는 성질을 의미합니다.

https://developer.mozilla.org/en-US/docs/Glossary/Idempotent

Idempotent - MDN Web Docs Glossary: Definitions of Web-related terms | MDN

mozila에도 개별문서로 생성되어 있는 개념이긴 합니다만

역시 한국인에겐 읽기가 쉽지 않습니다.

https://ko.wikipedia.org/wiki/HTTP

 위키피디아의 HTTP 문서에서 찾아 볼 수 있는 요약표입니다.

멱등성을 보장하지 못하는 HTTP 메서드로 총 세가지를 찾아 볼 수 있는데

POST , CONNECT , PATCH가 있네요

PATCH는 왜 멱등성이 보장 되지 못하는지 위 링크를 참고해보면 알 수 있고

POST는 리소스를 추가하는 행위를 하는 메서드다보니 같은 요청을 여러번 반복하면

같은 리소스가 여러번 추가되는 행위를 낳아 멱등성이 보장되지 않게됩니다.

 

위 표에서 멱등성과 함께 안전 / 캐시가능성에 대한 체크항목도 찾아 볼 수 있는데

이 역시도 알아두면 좋을 것 같습니다만 너무 분량이 길어졌으므로 3단계로 넘어가겠습니다.

---

🙉REST 성숙도 모델 3단계 Hypermedia Controls

 

마지막 단계인 3단계는 HATEOAS라고 표현할 수 있습니다. 이는 약어로 쭉 풀어 쓰게되면

Hypermedia As The Engine Of Application State

라는 긴... 하나의 영어 문장이 됩니다.

3단계의 요청은 2단계와 동일하지만 응답 부분에서 그 차이가 발생합니다.

 

3단계에서 요청에 대한 응답은 리소스의 URI를 포함한 링크 요소를 삽입하여서 작성해야합니다.

---

🙉Open API와 API Key

오픈 API는 개발자라면 누구나 사용할 수 있도록 공개된 API를 말하며

개발자에게 프로그래밍 적인 권한을 제공해주는 API입니다.

반의어로는 Private API를 들 수 있으며 대표적인 OPEN API로는 네이버 지도 / 구글 맵이나

대한민국 정부에서 제공하는 공공데이터 등을 들 수 있습니다.

 

다만 이러한 오픈 API들도 무제한으로 마구 사용할 수 있는 것은 아닌 경우가 많으며

대개 API를 공급하는 측이 제시하는 규칙을 지켜야 하는 경우가 많습니다.

 예컨대 무료로는 사용량의 제한이 있거나 사용한 만큼 돈을 지불해야하는 경우 등을 들 수 있습니다.

 

또한 이러한 사용량의 제한 , 특정 이용자가 얼마나 사용했는지를 판단하기 위해서는

이용자를 특정할 필요성 또한 생깁니다.

 

따라서 API Key를 이용해 어떤 API Key에서 몇번의 API 이용이 발생했는지를 측정하곤 합니다.

간혹 API Key가 필요하지 않은 경우도 있지만... 제 경험으로는 대개 필요했던 것 같네요

이해했다고 생각할 때가 가장 무서울 때다.