로이 필딩의 REST: 현대 웹 API를 규정하는 제약

로이 필딩의 REST가 여전히 중요한 이유

로이 필딩은 단순히 API 유행어에 붙은 이름이 아니다. 그는 HTTP와 URI 명세의 주요 저자 중 한 명이며, 박사 논문에서 **REST(Representational State Transfer)**라는 아키텍처 스타일을 설명하여 웹이 지금처럼 잘 동작하는 이유를 제시했다.

그 기원은 중요하다 — REST는 '멋진 엔드포인트'를 만들려고 발명된 것이 아니다. 그것은 전 세계적으로 혼란스러운 네트워크가 확장 가능하도록 하는 제약을 설명하는 방식이었다: 많은 클라이언트, 많은 서버, 중간자, 캐싱, 부분적 실패, 지속적인 변화 등.

이 글에서 얻을 것들

두 개의 'REST API'가 완전히 다르게 느껴지거나 작은 설계 선택이 나중에 페이지네이션 문제, 캐싱 혼란, 혹은 깨지는 변경으로 이어지는 이유가 궁금했다면—이 가이드는 그런 놀라움을 줄이기 위해 작성되었다.

얻을 수 있는 것들:

• 더 명확한 API 설계·평가 의사결정
• 팀과의 트레이드오프 논의에 쓸 더 나은 어휘
• 실제 프로젝트에서 중요한 REST 아이디어에 대한 실용적 감각

한 페이지로 보는 REST: 표준이 아닌 스타일

REST는 체크리스트나 프로토콜, 인증이 아니다. 필딩은 이를 아키텍처 스타일로 묘사했다: 함께 적용될 때 웹처럼 확장되는 시스템을 만들어내는 제약들의 집합—사용하기 간단하고, 시간이 지나도 진화할 수 있으며, 중간자(프록시, 캐시, 게이트웨이)와의 조정 없이도 잘 동작하는 시스템.

REST가 해결하려던 문제

초기 웹은 많은 조직, 서버, 네트워크, 클라이언트 유형에 걸쳐 작동해야 했다. 중앙 통제 없이 성장하고, 부분적 실패를 견디며, 새로운 기능이 등장해도 기존 것을 깨지 않아야 했다. REST는 식별자, 표현, 표준 연산 같은 널리 공유되는 개념을 선호함으로써 맞춤형이고 강하게 결합된 계약 대신 그런 요구를 해결했다.

평이한 용어로 '아키텍처 제약'

제약은 설계의 자유를 제한하는 규칙으로, 그 대가로 이점을 얻는다. 예를 들어 서버 측 세션 상태를 포기하면 어떤 서버 노드든 요청을 처리할 수 있게 되어 가용성과 확장성이 좋아진다. 각 REST 제약은 비슷한 거래를 한다: 임의의 유연성을 줄이는 대신 예측 가능성과 진화 가능성을 얻는다.

REST 대 'REST-유사' API

많은 HTTP API가 REST 아이디어(HTTP 위의 JSON, URL 엔드포인트, 상태 코드 등)를 차용하지만 전체 제약 집합을 적용하지는 않는다. 그게 '틀리다'는 의미는 아니다—제품 일정이나 내부 전용 필요에 따라 흔히 발생하는 일이다. 단지 차이를 이름 붙여 구분하는 것이 유용하다: API는 완전한 REST가 아니더라도 자원 지향적일 수 있다.

한 문장 정신 모델

REST 시스템을 리소스(URL로 식별할 수 있는 것들)로 보고, 클라이언트는 표현(JSON이나 HTML 같은 리소스의 현재 뷰)을 통해 상호작용하며, 링크(다음 행동과 관련 리소스)를 따라 움직인다고 생각해 보라. 클라이언트는 비밀스러운 별도 규칙이 필요 없고, 표준 의미론을 따르며 링크를 통해 탐색한다—브라우저가 웹을 이동하는 것과 같은 방식이다.

자원과 표현: 핵심 어휘

제약과 HTTP 세부 사항에 빠지기 전에, REST는 단순한 어휘 전환에서 시작한다: 액션 대신 리소스로 생각하라.

리소스 = 식별 가능한 명사

리소스는 시스템에서 주소 지정 가능한 '것': 사용자, 인보이스, 상품 카테고리, 장바구니 등이다. 중요한 것은 이것이 정체성을 가진 명사라는 점이다.

그래서 /users/123은 자연스럽게 읽힌다: ID 123인 사용자를 식별한다. /getUser나 /updateUserPassword 같은 액션형 URL과 비교하면, 그것들은 작동하는 '동사'를 설명한다.

REST는 행동을 못 하게 하지 않는다. 대신 행동은 통일 인터페이스(HTTP API의 경우 보통 GET/POST/PUT/PATCH/DELETE 같은 메서드)를 통해 리소스 식별자에 적용되어야 한다고 말한다.

표현 = 리소스의 뷰

표현은 특정 시점의 리소스의 스냅샷이나 뷰를 전송하는 것이다. 동일한 리소스는 여러 표현을 가질 수 있다.

예를 들어, 리소스 /users/123은 앱을 위한 JSON으로 표현될 수도 있고, 브라우저를 위한 HTML로 표현될 수도 있다.

GET /users/123
Accept: application/json

다음과 같은 응답을 반환할 수 있다:

{
  "id": 123,
  "name": "Asha",
  "email": "[email protected]"
}

반면:

GET /users/123
Accept: text/html

는 동일한 사용자 정보를 렌더링한 HTML 페이지를 반환할 수 있다.

핵심 아이디어: 리소스는 JSON이 아니며 HTML도 아니다. 그것들은 그저 리소스를 표현하는 형식일 뿐이다.

이런 관점이 API 설계를 어떻게 바꾸는가

리소스와 표현 중심으로 API를 모델링하면 몇 가지 실용적 결정이 쉬워진다:

• 이름이 안정적이다. /users/123은 UI, 워크플로, 데이터 모델이 진화해도 유효하게 남는다.
• 엔드포인트가 단순해진다. 모든 작업마다 새로운 URL을 발명하는 대신 리소스 URL을 재사용하고 메서드나 표현으로 변화를 준다.
• 클라이언트 코드의 결합도가 낮아진다. 클라이언트는 '사용자를 가져와라' 또는 '사용자 필드를 업데이트하라'에 집중하고, 행동 목록을 외워야 하지 않는다.

이 리소스 우선 사고방식은 REST 제약이 기반을 두는 토대다. 이것이 없으면 'REST'는 종종 'HTTP 위의 JSON과 괜찮은 URL 패턴'으로 축소된다.

제약 1: 클라이언트–서버 분리

클라이언트–서버 분리는 책임의 명확한 분리를 강제하는 REST의 방식이다. 클라이언트는 사용자 경험(사용자가 보는 것과 하는 것)에 집중하고, 서버는 데이터, 규칙, 지속성(무엇이 사실이고 허용되는지)에 집중한다. 이런 관심사의 분리는 각각이 상대편을 재작성하지 않고도 변경될 수 있게 한다.

클라이언트와 서버에 무엇이 위치하는가?

일상적 용어로 클라이언트는 '프레젠테이션 레이어'다: 화면, 내비게이션, 빠른 피드백을 위한 폼 검증, 낙관적 UI 동작(예: 새 댓글 즉시 표시) 등. 서버는 '진실의 원천'이다: 인증, 권한 부여, 비즈니스 규칙, 데이터 저장, 감사, 장치 간 일관성이 필요한 모든 것.

실용적 규칙: 결정이 보안, 금전, 권한, 공유 데이터 일관성에 영향을 미친다면 서버에 있어야 한다. 경험(레이아웃, 로컬 입력 힌트, 로딩 상태)에만 영향을 주는 결정은 클라이언트에 두라.

현대 앱 패턴과의 적합성

이 제약은 일반적인 설정과 직접적으로 대응한다:

• SPA + API: 웹 앱(React/Vue 등)은 UI를 반복적으로 개선하고, API는 리소스를 계속 제공한다.
• 모바일 앱: iOS와 Android 클라이언트가 동일한 서버 규칙과 엔드포인트를 공유할 수 있다.
• 서드파티 통합: 파트너는 UI 없이도 동일한 서버 기능을 소비할 수 있다.

클라이언트–서버 분리는 '하나의 백엔드, 많은 프런트엔드'를 현실화한다.

일반적인 함정: UI 상태가 서버 세션으로 유출되는 경우

흔한 실수는 UI 워크플로 상태(예: '결제의 어느 단계인지')를 서버에 저장하는 것이다. 이것은 백엔드를 특정 화면 흐름에 결합시키고 확장을 어렵게 만든다.

각 요청에 필요한 문맥을 보내거나(또는 저장된 리소스에서 유도하라) 서버가 리소스와 규칙에 집중하도록 하라—특정 UI가 어떻게 진행 중인지 기억하게 하지 마라.

제약 2: 무상태 상호작용

무상태성은 서버가 요청 간에 클라이언트에 대해 아무것도 기억할 필요가 없다는 의미다. 각 요청은 그것을 이해하고 올바르게 응답하는 데 필요한 모든 정보를 포함한다—호출자가 누구인지, 무엇을 원하는지, 처리에 필요한 문맥 등.

왜 중요한가

요청이 독립적일 때 로드 밸런서 뒤에 서버를 추가하거나 제거해도 '어떤 서버가 내 세션을 알고 있느냐'를 걱정할 필요가 없다. 이는 확장성과 복원력을 향상시킨다: 어떤 인스턴스든 어떤 요청이든 처리할 수 있다.

또한 운영이 단순해진다. 디버깅이 더 쉬워지는 경우가 많다. 전체 문맥이 요청(및 로그)에 보이기 때문에 서버 메모리에 숨겨진 상태보다 이해하기 쉽다.

실제 API에서 느끼는 트레이드오프

무상태 API는 보통 호출마다 약간 더 많은 데이터를 보낸다. 서버 세션에 의존하는 대신 클라이언트가 매번 자격 증명과 문맥을 포함한다.

또한 페이지네이션이나 다단계 체크아웃 같은 '상태ful' 사용자 흐름에 대해 명시적이어야 한다. REST는 다단계 경험을 금지하지 않는다—다만 상태를 클라이언트에 두거나 식별 가능하고 검색 가능한 서버 측 리소스로 옮기도록 압박한다.

실용적 패턴(그리고 그들이 해결하는 문제들)

• 인증 토큰(예: Bearer JWT): 모든 요청에 Authorization: Bearer … 헤더를 포함해 어떤 서버든 인증할 수 있게 한다.
• 멱등성 키(Idempotency keys): '결제 생성' 같은 작업에 대해 클라이언트가 Idempotency-Key를 보내면 재시도가 중복 작업을 발생시키지 않는다.
• 상호 추적 ID(Correlation IDs): X-Correlation-Id 같은 헤더는 분산 시스템과 로그에서 한 사용자 행동을 추적하게 한다.

페이지네이션의 경우 '서버가 3페이지를 기억한다' 같은 방법을 피하라. ?cursor=abc 같은 명시적 파라미터나 클라이언트가 따라갈 수 있는 next 링크를 선호해 탐색 상태를 응답에 보관하라.

제약 3: 캐시 가능한 응답

캐싱은 이전 응답을 안전하게 재사용해 클라이언트(또는 중간자)가 동일한 작업을 다시 서버에 묻지 않도록 하는 것이다. 잘하면 사용자 지연이 줄고 서버 부하가 줄어든다—API 의미를 바꾸지 않으면서.

'캐시 가능'이 실제로 의미하는 것

응답이 어떤 기간 동안 동일한 페이로드를 다른 요청이 받아도 안전할 때 캐시 가능하다고 한다. HTTP에서는 캐싱 헤더로 그 의도를 전달한다:

• Cache-Control: 얼마나 오래 보관할지, 공유 캐시에 저장할 수 있는지 등을 지정하는 주 스위치
• ETag와 Last-Modified: 클라이언트가 '변했는가?' 하고 확인할 때 저비용 '변경 없음(304)' 응답을 가능하게 하는 검증자
• Expires: 신선도 표현의 오래된 방식, 여전히 보이는 경우가 있다

이는 '브라우저 캐싱'보다 큰 의미를 가진다. 프록시, CDN, API 게이트웨이, 모바일 앱도 규칙이 명확하면 응답을 재사용할 수 있다.

보통 캐시해도 좋은 것(그리고 그렇지 않은 것)

좋은 후보:

• 공용, 모든 사용자에게 동일한 데이터(상품 카탈로그, 문서, 사용자별이 아닌 기능 플래그)
• 자주 변하지 않는 읽기 전용 리소스(정적 구성, 참조 데이터)
• 쿠키나 인증에 의존하지 않는 GET 응답

보통 캐시하지 않는 것이 좋은 후보:

• 계정에 묶인 개인 데이터(프로필, 주문, 메시지)
• 인증 관련 응답(토큰 교환, 세션 상태)
• 사용자별로 달라지는 모든 것(명시적으로 처리하지 않는 한)

실용적 결과

• 더 빠른 페이지와 반응성 향상(네트워크 대기 시간 감소)
• 낮은 서버·DB 비용(반복 계산 감소)
• '요청 한도' 사건 감소(캐시된 조회가 요청량을 줄임)

핵심 아이디어: 캐싱은 사후 고려가 아니다. 신선도와 검증을 명확히 전달하는 API에 보상을 주는 REST 제약이다.

제약 4: 통일 인터페이스(실제 의미)

통일 인터페이스는 종종 '읽기는 GET, 생성은 POST를 써라'로 오해된다. 그건 작은 일부에 불과하다. 필딩의 아이디어는 더 크다: 클라이언트가 모든 엔드포인트의 특별한 지식을 필요로 하지 않을 만큼 API가 일관되게 느껴야 한다.

통일 인터페이스의 네 부분

1. 리소스의 식별: 안정적인 식별자(보통 URL)로 '것'을 명명한다. /orders/123 같은 식별자.

2. 표현을 통한 조작: 클라이언트는 표현(JSON, HTML 등)을 보내 리소스를 변경한다. 서버가 리소스를 제어하고, 클라이언트는 그 표현을 교환한다.

3. 자기 설명적 메시지: 각 요청/응답은 처리 방법을 이해하기에 충분한 정보를 담아야 한다—메서드, 상태 코드, 헤더, 미디어 타입, 명확한 바디 등. 의미가 외부 문서에 숨겨져 있다면 클라이언트는 강하게 결합된다.

4. 하이퍼미디어(HATEOAS): 응답에는 링크와 허용된 행동이 포함되어 클라이언트가 모든 URL 패턴을 하드코딩하지 않고도 워크플로를 따라갈 수 있어야 한다.

왜 결합도를 줄이는가

일관된 인터페이스는 클라이언트를 내부 서버 세부사항에 덜 의존하게 만든다. 시간이 지나면 깨지는 변경이 줄고, '특별한 경우'가 줄며, 팀이 엔드포인트를 발전시켜도 재작업이 덜 필요해진다.

적용할 수 있는 실용적 휴리스틱

• 상태 코드를 일관되게 사용: 예: 읽기 성공 200, 생성 201(및 Location), 검증 문제 400, 인증 401/403, 리소스 없음 404.
• 오류 형식 표준화: 예시 필드: code, message, details, requestId.
• 미디어 타입과 헤더를 의미 있게 유지(Content-Type, 캐싱 헤더), 메시지가 스스로 설명하게 하라.

통일 인터페이스는 예측 가능성과 진화 가능성에 관한 것이지 단순히 '정확한 메서드'에 관한 것이 아니다.

자기 설명적 메시지: 이해를 위한 설계

'자기 설명적' 메시지는 수신자가 별도의 지식 없이도 해석 방법을 알려주는 메시지다. 클라이언트(또는 중간자)가 응답이 '무슨 의미인지' HTTP 헤더와 바디만 보고 이해할 수 없다면, 당신은 HTTP 위에 사설 프로토콜을 만든 것이다.

페이로드를 설명하기 위해 미디어 타입 사용

가장 쉬운 개선은 Content-Type(보내는 것)과 종종 Accept(원하는 것)를 명시하는 것이다. Content-Type: application/json 응답은 기본 파싱 규칙을 알려주지만, 의미가 중요할 때는 벤더 또는 프로파일 기반 미디어 타입으로 더 명확히 할 수 있다.

접근법 예시:

• 일반 미디어 타입 + 안정된 필드: application/json과 유지되는 스키마. 대부분 팀에 가장 쉬움.
• 벤더 미디어 타입: application/vnd.acme.invoice+json 같은 특정 표현을 신호.
• 프로파일: application/json을 유지하고 profile 파라미터나 링크로 의미를 정의.

버전 관리와 호환성(클라이언트를 깨지지 않게)

버전 관리는 기존 클라이언트를 보호해야 한다. 인기 있는 옵션:

• URL 버전 관리(/v1/orders): 명확하지만 표현을 포크하는 경향을 불러올 수 있다.
• 헤더 또는 미디어 타입 버전 관리(Accept를 통해): URL을 안정적으로 유지하고 '의미'를 메시지의 일부로 만든다.
• 추가적 진화: 새 필드를 추가하고 옛 필드를 계속 동작하게 유지; 점진적으로 폐기.

무엇을 선택하든, 기본적으로 역호환성을 목표로 하라: 필드 이름을 함부로 바꾸지 말고, 의미를 조용히 변경하지 말며, 제거는 브레이킹 변경으로 다뤄라.

일관된 오류와 명확한 명명

오류가 어디서나 동일하게 보이면 클라이언트가 더 빨리 배운다. 하나의 오류 형태(예: code, message, details, traceId)를 선택해 모든 엔드포인트에서 사용하라. 명확하고 예측 가능한 필드 이름(createdAt vs created_at)을 사용하고 한 가지 규칙을 지켜라.

문서화는 도움이 되지만—메시지 자체의 명확성이 우선

문서는 채택을 가속화하지만, 의미가 문서에만 존재해서는 안 된다. 클라이언트가 status: 2가 '결제 완료'인지 '대기'인지 알기 위해 위키를 봐야 한다면 메시지는 자기 설명적이지 않다. 잘 설계된 헤더, 미디어 타입, 읽기 쉬운 페이로드는 문서 의존도를 줄이고 시스템을 더 쉽게 진화시킨다.

하이퍼미디어(HATEOAS): 가장 많이 건너뛰는 REST 아이디어

하이퍼미디어(HATEOAS: Hypermedia As The Engine Of Application State)는 클라이언트가 API의 다음 URL을 미리 '알아야' 하지 않아야 한다는 뜻이다. 대신 각 응답은 링크로서 발견 가능한 다음 단계를 포함한다: 어디로 가야 하는지, 가능한 행동이 무엇인지, 때로는 어떤 HTTP 메서드를 사용해야 하는지도.

실무적 예시

클라이언트가 /orders/{id}/cancel 같은 경로를 하드코딩하는 대신, 서버가 제공하는 링크를 따라간다. 서버는 사실상 '현재 리소스 상태에서 허용되는 움직임은 이렇다'고 말하는 것이다.

{
  "id": "ord_123",
  "status": "pending",
  "total": 49.90,
  "_links": {
    "self":   { "href": "/orders/ord_123" },
    "payment":{ "href": "/orders/ord_123/payment", "method": "POST" },
    "cancel": { "href": "/orders/ord_123", "method": "DELETE" }
  }
}

주문이 나중에 paid가 되면 서버는 cancel을 빼고 refund를 추가할 수 있다—잘 동작하는 클라이언트는 깨지지 않는다.

하이퍼미디어가 가장 유용한 경우

하이퍼미디어는 흐름이 진화할 때 빛난다: 온보딩 단계, 체크아웃, 승인, 구독 등 상태, 권한, 비즈니스 규칙에 따라 '다음에 허용되는 것'이 바뀌는 프로세스.

또한 하드코딩된 URL과 깨지기 쉬운 클라이언트 가정을 줄인다. 라우트를 재구성하거나 새 행동을 도입하거나 오래된 행동을 사용 중단해도 링크 관계의 의미를 유지하면 클라이언트는 계속 동작한다.

팀들이 건너뛰는 이유(그리고 잃는 것)

팀은 링크 형식 정의, 관계 이름 합의, 클라이언트 개발자에게 링크를 따라가도록 교육하는 추가 작업 때문에 종종 HATEOAS를 건너뛴다.

잃는 것은 REST의 핵심 이점인 느슨한 결합이다. 하이퍼미디어가 없으면 많은 API는 'HTTP 위의 RPC'가 된다—HTTP를 쓰지만 클라이언트는 문서와 고정된 URL 템플릿에 강하게 의존한다.

제약 5: 계층화 시스템

계층화 시스템은 클라이언트가 응답을 '실제' 오리진 서버가 제공했는지, 그 도중의 중간자가 제공했는지 알 필요가 없고(보통 모른다는 것), 알 필요도 없다는 것을 의미한다. 이 레이어는 API 게이트웨이, 리버스 프록시, CDN, 인증 서비스, WAF, 서비스 메쉬, 마이크로서비스 간 내부 라우팅 등을 포함할 수 있다.

레이어가 유용한 이유

레이어는 경계를 깔끔하게 만든다. 보안 팀은 모든 백엔드 서비스를 바꾸지 않고 엣지에서 TLS, 요청 속도 제한, 인증, 요청 검증을 시행할 수 있다. 운영팀은 게이트웨이 뒤에서 수평 확장을 하거나 CDN에 캐싱을 추가하거나 인시던트 중에 트래픽을 전환할 수 있다. 클라이언트에게는 하나의 안정된 API 엔드포인트, 일관된 헤더, 예측 가능한 오류 형식이라는 장점이 있다.

실제에서 느끼는 트레이드오프

중간자는 숨겨진 지연(추가 홉, 추가 핸드셰이크)을 도입하고 디버깅을 어렵게 만들 수 있다: 버그가 게이트웨이 규칙, CDN 캐시, 혹은 오리진 코드 중 어디에 있는지 알기 힘들다. 서로 다른 레이어가 다르게 캐싱하면 혼란스러울 수 있고, 게이트웨이가 캐시 키에 영향을 주는 헤더를 재작성하면 문제가 생긴다.

레이어가 해가 되지 않게 하는 실용 팁

• 추적 ID를 끝까지 전파: 요청 ID를 받아(또는 생성) 모든 홉에 걸쳐 전파하고 응답과 로그에 포함하라.
• 오류 전파를 명시적으로 만들라: 업스트림 실패를 명확히 매핑하라(모든 문제를 일반적인 500으로 바꾸지 마라).
• 홉별 타임아웃 설정: 게이트웨이 타임아웃, 업스트림 타임아웃, 클라이언트 타임아웃을 정렬해 '미스테리' 연결 끊김을 피하라.
• 캐싱 동작 문서화: 어떤 응답이 캐시 가능하고 어떤 헤더를 중간자가 보존해야 하는지 명확히 하라.

레이어는 시스템이 관찰 가능하고 예측 가능할 때 강력한 도구다.

제약 6(선택): 코드-온-디맨드

코드-온-디맨드는 REST 제약 중 명시적으로 선택적인 하나다. 이는 서버가 클라이언트에 실행 가능한 코드를 보내 클라이언트를 확장할 수 있다는 뜻이다. 클라이언트가 모든 동작을 미리 포함하는 대신 필요할 때 새로운 로직을 다운로드할 수 있다.

웹의 친숙한 예: 자바스크립트

웹 페이지를 불러와 상호작용이 가능해진 적이 있다면—폼 검증, 차트 렌더링, 테이블 필터링 등을 브라우저에서 하는 것—이미 코드-온-디맨드를 사용한 것이다. 서버는 HTML과 데이터, 그리고 동작을 제공하는 JavaScript를 전달한다.

이는 브라우저가 범용 클라이언트로 남는 큰 이유 중 하나다. 사이트는 사용자가 전체 애플리케이션을 설치하지 않아도 새 기능을 전달할 수 있다.

왜 선택적인가(그리고 많은 API가 건너뛰는 이유)

다른 제약이 이미 확장성, 단순성, 상호운용성을 제공하기 때문에 REST는 코드-온-디맨드 없이도 '작동'한다. API는 순수하게 리소스 지향적일 수 있고 JSON 같은 표현을 제공하면서도 충분하다.

실제로 많은 현대 웹 API는 실행 가능한 코드를 보내는 것을 피한다. 그 이유는 복잡성을 높이기 때문이다:

• 보안: 실행 가능한 코드는 공격면을 넓힌다(주입, 공급망 문제, 악성 스크립트).
• 콘텐츠 정책: 브라우저는 Content Security Policy(CSP) 같은 제한을 강제하고 조직은 인라인 스크립트나 알 수 없는 출처를 차단할 수 있다.
• 감사 및 규정 준수: 클라이언트에서 어떤 코드가 언제 실행됐는지 증명하기 어렵다.

코드-온-디맨드가 여전히 유용한 경우

클라이언트 환경을 통제하고 UI 동작을 빠르게 배포해야 하거나, '플러그인'이나 규칙을 서버에서 다운로드하는 얇은 클라이언트를 원할 때 유용할 수 있다. 그러나 이는 추가 도구로 취급하는 것이 좋다—필수는 아니다.

핵심 요약: REST를 완전히 따르기 위해 코드-온-디맨드가 필요하지 않다—많은 생산 환경 API가 이를 따르지 않고도 운영된다. 이 제약은 확장의 선택지에 관한 것이다.

오늘날 REST 적용: 실용적 선택과 흔한 실수

대부분 팀이 REST를 '거부'하는 것은 아니다—그들은 HTTP를 전송 계층으로 두고 핵심 제약을 조용히 버리는 'REST-유사' 스타일을 채택한다. 그건 괜찮을 수 있다, 단 그것이 나중에 깨지기 쉬운 클라이언트와 비용이 많이 드는 재작업으로 이어지는 우연한 결과가 아니면 된다.

흔한 REST-유사한 지름길(그리고 그 이유)

몇 가지 패턴이 반복적으로 나타난다:

• RPC 엔드포인트: /doThing, /runReport, /users/activate—이름 붙이기 쉽고 연결하기 쉽다.
• 동사 중심 URL: /createOrder, /updateProfile, /deleteItem—HTTP 메서드가 사후 생각이 된다.
• 숨겨진 세션: '무상태' API이면서도 스티키 세션, 서버 메모리, 암묵적 워크플로 상태에 의존한다.

이 선택들은 초기에는 내부 함수 이름과 비즈니스 작업을 반영해 생산적으로 느껴진다.

나중에 나타나는 결과

• 깨지기 쉬운 클라이언트: 클라이언트가 특정 엔드포인트 모양과 애드혹 동작에 의존하면, 작은 서버 리팩터링도 브레이킹 변경이 된다.
• 버전 관리의 어려움: URL이 행동을 인코딩하면 행동을 버전 관리하게 되고 표현을 진화시키기 어렵다.
• 캐시 미스(및 더 높은 지연): 캐시 헤더를 무시하거나 모든 것을 POST로 처리하면 중간자가 도와줄 수 없다.
• 확장 문제: 숨겨진 서버 측 세션 상태는 수평 확장을 복잡하게 하고, 실패 복구를 어렵게 만든다.

실용적 '얼마나 REST인가' 체크리스트

다음은 '우리는 얼마나 REST에 가까운가?'를 점검하는 리뷰다:

1. 행동이 아닌 리소스를 명명하는가: /orders/{id}를 /createOrder보다 선호한다.
2. HTTP 메서드를 의도적으로 사용하는가: GET은 조회, POST는 생성, PUT/PATCH는 업데이트, DELETE는 제거.
3. 요청이 독립적인가: 클라이언트가 '어떤 단계에 있는지' 이해하기 위해 서버 메모리에 의존하지 않는다.
4. 안전한 곳에서 캐싱을 활용하는가: GET 응답에 Cache-Control, ETag, Vary를 정의한다.
5. 오류와 미디어 타입을 표준화하는가: 일관된 상태 코드와 응답 형태는 특수 사례를 줄인다.

실제 빌드할 때 나타나는 모습

REST 제약은 단지 이론이 아니다—출시할 때 느껴지는 안전장치다. 예컨대 빠르게 API를 생성할 때(React 프런트엔드와 Go + PostgreSQL 백엔드를 스캐폴딩할 때) 가장 쉬운 실수는 '연결하기 가장 빠른 방식'이 인터페이스를 결정하도록 두는 것이다.

만약 당신이 채팅으로 웹 앱을 만드는 플랫폼인 Koder.ai 같은 곳을 사용한다면, 이 REST 제약들을 초기에 대화에 포함시키는 것이 도움이 된다—우선 리소스 이름 짓기, 무상태 유지, 일관된 오류 모양 정의, 어디서 캐싱이 안전한지 결정하기. 그렇게 하면 빠른 반복 중에도 예측 가능하고 진화하기 쉬운 API가 만들어진다. (그리고 Koder.ai가 소스 코드 내보내기를 지원하므로 요구가 진화함에 따라 API 계약과 구현을 계속 다듬을 수 있다.)

API 및 웹 앱 팀을 위한 요약

핵심 리소스를 먼저 정의하고, 그다음 제약을 의식적으로 선택하라: 캐싱이나 하이퍼미디어를 건너뛰고 있다면 그 이유와 대신 무엇을 사용하는지 문서화하라. 목표는 순수성이 아니다—명확성이다: 안정된 리소스 식별자, 예측 가능한 의미론, 그리고 시스템이 진화할 때 클라이언트를 강건하게 만드는 명시적 트레이드오프.