245. RESTful API 성숙도 모델 (Richardson Maturity Model)

⚠️ 이 문서는 전 세계 개발자들이 너도나도 "우리 API는 REST API입니다!"라고 뻥을 치지만, 막상 코드를 까보면 전혀 REST의 철학을 지키지 않은 엉터리 API(단순 RPC)가 난무하는 참상을 바로잡기 위해, **레오나르드 리처드슨(Leonard Richardson)이 "진짜 100% 완벽한 REST API가 되려면 이 4가지 진화 단계(Level 0 ~ 3)를 거쳐야 한다"고 정의한 'REST 성숙도 평가 모델(RMM)'**을 다룹니다.

핵심 인사이트 (3줄 요약)

  1. 본질: 네가 만든 API가 단순한 '원격 함수 호출(RPC)' 수준인지, 아니면 진정한 '웹 철학(HTTP/URI)을 이해하는 자원(Resource) 지향 구조'인지를 판별하는 4계단짜리 성적표다.
  2. 가치: 대부분의 기업 API는 Level 2에 머물러 있다. 궁극의 경지인 Level 3(HATEOAS)에 도달하면, 클라이언트(프론트엔드)는 서버의 API 주소가 바뀌어도 하드코딩을 뜯어고칠 필요 없이, 서버가 던져주는 '하이퍼링크(안내판)'만 따라가며 100% 스스로 길을 찾는 미친 자율성을 얻게 된다.
  3. 기술 체계: HTTP를 그냥 껍데기로 쓰는 Level 0, 명사(URI)로 자원을 쪼개는 Level 1, 동사(HTTP Method)로 행동을 표현하는 Level 2, 마지막으로 응답에 다음 행동의 링크(Link)를 쥐여주는 **Level 3 (HATEOAS)**로 구성된다.

Ⅰ. 밑바닥부터 HTTP의 재발견까지 (Level 0 ~ Level 2)

URL에 get_user라고 동사를 적어놨다면 너는 REST를 모르는 자다.

  1. Level 0 (The Swamp of POX) - 단순 함수 호출:
    • HTTP 프로토콜을 그냥 남의 컴퓨터에 있는 함수(메서드)를 실행하기 위한 터널(껍데기)로만 쓰는 가장 원시적인 상태다 (SOAP나 XML-RPC 방식).
    • 모든 요청을 무조건 POST 하나로만 쏘며, 주소도 단 하나 http://api.com/api 로 통일한다.
    • 보내는 데이터 안에 {"action": "deleteUser", "id": 1} 라고 적어서 쏜다. REST 철학이 0%다.
  2. Level 1 (Resources) - 명사(자원)의 도입:
    • 조금 발전했다. 모든 행동을 1개의 통로에 몰아넣지 않고, 내가 다루려는 **자원(Resource)**마다 각자의 주소(URI) 방을 뚫어주기 시작한다.
    • 예: 사람을 다룰 땐 http://api.com/users/1 방을 쓰고, 주문을 다룰 땐 http://api.com/orders/1 방을 쓴다.
    • 하지만 여전히 HTTP 메서드는 멍청하게 GET이나 POST 딱 하나만 주구장창 쓴다.
  3. Level 2 (HTTP Verbs) - 동사(Method)의 활용:
    • 대부분의 실무 개발자들이 "우린 REST 쓴다!"라고 말하는 수준(사실상 De Facto 표준)이다.
    • 자원(명사)과 행동(동사)을 완벽하게 분리한다. URL에는 절대 동사(delete, update)를 쓰지 않고, 행동은 반드시 **HTTP Method(GET, POST, PUT, DELETE)**로만 표현한다.
    • GET /users/1 (1번 유저 가져와), DELETE /users/1 (1번 유저 지워!). 완벽하고 깔끔하다.

📢 섹션 요약 비유: 도서관에 비유해 봅니다. Level 0은 도서관 입구의 우체통 딱 1개에 "10번 책 버려라"라는 편지를 쑤셔 넣는 방식입니다. Level 1은 도서관에 [책], [회원]이라는 전용 창구가 생겼지만, 창구 직원이 모든 요구를 "주세요(POST)" 하나로만 처리합니다. Level 2는 완벽합니다. [책] 창구(자원)에 가서, 직원의 멱살을 잡으면(DELETE), 직원이 책을 불태우고 "성공(200 OK)" 팻말을 들어 올리는 완벽한 분업화입니다.

Ⅱ. 궁극의 경지 Level 3: HATEOAS의 마법

서버가 클라이언트의 손에 다음 지도를 쥐여준다.

  1. Level 3 (HATEOAS)의 개념:
    • HATEOAS(Hypermedia As The Engine Of Application State). 이 무시무시한 이름의 핵심은 **"응답(Response) JSON 데이터 안에, 클라이언트가 다음에 할 수 있는 행동의 API 주소(Link)를 같이 묶어서 던져줘라!"**는 철학이다.
  2. HATEOAS 적용 전후 비교:
    • Level 2의 응답: 잔고 조회 API를 불렀더니 {"account_id": 1, "balance": 100} 이 끝이다. 이 돈을 '송금'하려면 프론트엔드 개발자는 송금 API 주소(/transfer)를 자기 자바스크립트 코드에 하드코딩해 놔야 한다.
    • Level 3의 응답: 잔고 조회 API를 부르면 이런 답변이 온다.
      {
  "account_id": 1, "balance": 100,
  "links": [
    {"rel": "self", "href": "/accounts/1"},
    {"rel": "transfer", "href": "/accounts/1/transfer"},
    {"rel": "close", "href": "/accounts/1/close"}
  ]
}
    • 서버가 100원과 함께 "너 돈 있으니까 [송금]도 할 수 있고, [계좌 해지]도 할 수 있어. 그 주소들은 이거야!"라고 다음 행동 지침(Link)을 촥 뿌려준다.
  3. 궁극의 독립성 (Decoupling):
    • 나중에 서버 개발자가 송금 API 주소를 /transfer에서 /send-money로 몰래 바꿨다 치자.
    • Level 2 프론트엔드는 주소를 하드코딩해 놨으니 404 에러가 터지며 멸망한다.
    • Level 3 프론트엔드는 자바스크립트 코드를 1도 안 고쳐도 된다. 어차피 서버가 응답할 때마다 바뀐 새 주소(/send-money)를 links 필드에 담아서 주니까, 그냥 그 링크 변수만 잡아서 누르면 완벽하게 돌아간다.

📢 섹션 요약 비유: 지하철역에서 출구를 찾습니다. Level 2는 길 가는 사람에게 "3번 출구 어때요?" 물어보면 "거기 열려있어요"라고 대답만 해줍니다(데이터만 줌). 저는 제 머릿속에 외워둔 지도(하드코딩)를 꺼내서 걸어가야 합니다. 지도가 바뀌면 길을 잃습니다. **Level 3(HATEOAS)**는 길을 물어보면, 직원이 대답과 함께 제 손에 **[다음 역으로 가는 밧줄(Hyperlink)]**을 쥐여주는 것입니다. 저는 그냥 뇌를 비우고(하드코딩 없이) 그 밧줄만 따라가면(링크 클릭), 내일 출구 공사가 나서 샛길이 뚫려도 밧줄 방향이 바뀌므로 절대 길을 잃지 않고 목적지에 도달하는 궁극의 자동화 가이드 시스템입니다.

Ⅲ. 실무에서의 타협 (Level 3는 낭비인가?)

이상은 높지만 현실의 장벽은 차갑다.

  1. HATEOAS 도입의 딜레마:
    • 레오나르도 리처드슨은 "Level 3가 아니면 진정한 REST API가 아니다!"라고 선언했지만, 2024년 현재 실리콘밸리 빅테크 기업들도 대부분 Level 2 수준에서 만족하고 산다.
  2. 왜 Level 3를 버리는가? (오버헤드):
    • 응답에 무조건 다음 행동의 링크(Links)들을 몽땅 계산해서 욱여넣어야 하니, 백엔드 서버의 코드가 엄청나게 더러워지고 JSON 용량이 2~3배로 폭발한다.
    • 프론트엔드 개발자도 그냥 API 명세서(Swagger) 보고 URL을 하드코딩하는 게 편하지, 매번 날아오는 links 배열을 파싱 해서 변수로 넣는 짓을 극도로 귀찮아한다.
  3. 그래도 HATEOAS가 필요한 곳:
    • 시스템의 API 주소가 매일같이 바뀌어야 하는 극한의 B2B 연동 시스템이거나, 버전 관리가 미친 듯이 까다로운 결제(Payment) 코어 모듈 등에서는 HATEOAS가 하드코딩의 저주를 푸는 생명줄 역할을 톡톡히 해낸다.

📢 섹션 요약 비유: Level 3(HATEOAS)는 모든 음식점 손님에게 매번 밥을 먹일 때마다 "다 드신 후 소화제는 화장실 옆 3번 복도 자판기에 있습니다"라는 길고 긴 안내 팸플릿(Links)을 무조건 억지로 쥐여주는 것과 같습니다. 손님이 이미 길을 다 외우고 있는 동네 단골(고정된 앱)이라면 이 팸플릿은 엄청난 자원 낭비와 귀찮음입니다. 하지만 매일 식당 구조가 바뀌는 테마파크 뷔페(동적 API 연동)라면 이 팸플릿이 없으면 손님이 미아가 되므로 필수불가결한 장치입니다.