CRM을 동기화하든, 배송 상태를 불러오든, SaaS 도구 두 개를 연결하든, 그 뒤에서 묵묵히 일하는 건 거의 항상 REST API예요. 평소엔 존재를 의식조차 안 하다가, 뭔가 고장 나야 비로소 알아차리죠.
흥미로운 건 개발자들 사이에서도 "어디까지가 RESTful이냐"를 두고 의견이 갈린다는 거예요. 용어가 워낙 느슨하게 쓰이다 보니, 한 Reddit 스레드에선 어떤 개발자가 이렇게 털어놓기도 했어요. "Roy Fielding 정의를 엄격히 따지면, 내가 진짜 RESTful API를 단 하나라도 만들어 봤는지 모르겠다." 비개발자가 아니라 현업 개발자의 말이에요. REST라는 개념은 Roy Fielding이 UC Irvine에서 쓴 2000년 박사 논문에서 출발했고, 그는 REST를 아키텍처 스타일, 즉 설계 제약의 묶음으로 정의했어요. 프로토콜도, 제품도, 내려받아 쓰는 명세도 아니죠.
그런데도 Postman 2025 State of the API Report를 보면 API 전문가의 93%가 REST를 써요. 거의 전부가 쓰는데, 정작 REST가 뭘 요구하는지는 많은 팀이 오해하고 있는 셈이죠. 이 글에서는 REST API의 6가지 핵심 특성을 쉬운 말로 풀고, 어떤 특성을 가장 자주 잘못 이해하는지 짚은 뒤, 스스로 점검할 성숙도 모델을 소개하고, REST를 SOAP·GraphQL·gRPC와 비교해 볼게요.
REST API란 무엇인가요? (쉽게 풀어쓴 정의)
REST(Representational State Transfer)는 소프트웨어 시스템이 네트워크 너머로 어떻게 소통할지를 정한 설계 규칙의 묶음이에요.
좀 더 정확히 말하면, REST는 무상태성·캐시 가능성·통일된 인터페이스 같은 제약을 정의하는 아키텍처 스타일이에요. 이 제약들은 클라이언트(브라우저, 모바일 앱, 자동화 도구)가 서버(데이터가 놓인 곳)와 어떻게 주고받을지를 안내해요. REST는 보통 HTTP 위에서 돌고 JSON을 주로 반환하지만, REST 자체가 특정 프로토콜이나 데이터 형식에 묶여 있진 않아요.
식사 자리의 예절을 떠올리면 쉬워요. 예절은 무슨 음식을 낼지, 무슨 언어로 말할지는 정하지 않아요. 대신 어떻게 음식을 건네고, 어떻게 더 청하고, 어떻게 식사가 끝났다고 알리는지를 정하죠. 같은 예절을 아는 두 사람은 초면이라도 막힘없이 대화해요. REST도 마찬가지예요.
REST가 아닌 것: REST는 설치하는 제품이 아니에요. HTTP나 SOAP 같은 프로토콜도 아니고요. API를 "RESTful"이라 부른다고 해서 Fielding의 제약을 전부 충족한다는 뜻도 아닙니다. 대개는 리소스 URL과 HTTP 메서드를 쓴다는 정도예요. "REST 비슷한 것"과 "진짜 RESTful" 사이의 거리가 업계에서 가장 큰 혼란의 원인 중 하나인데, 이건 잠시 뒤에 더 파볼게요.
한눈에 보는 REST API의 6가지 특성
세부로 들어가기 전에 요약표부터 볼게요. Fielding은 API가 RESTful로 인정받으려면 따라야 할 6가지 제약을 정의했어요. 그중 5개는 필수, 1개는 선택이에요.
| 제약 | 핵심 개념 | 주요 이점 | 구체적 예시 |
|---|---|---|---|
| 클라이언트-서버 | UI와 데이터 저장소를 분리 | 프런트엔드와 백엔드가 독립적으로 발전 가능 | React SPA가 REST API를 호출 |
| 무상태성 | 각 요청이 필요한 모든 맥락을 포함 | 수평 확장성, 세션 종속성 없음 | 모든 요청 헤더에 인증 토큰 전송 |
| 캐시 가능성 | 응답이 캐시 가능한지 명시 | 지연 시간과 서버 부하 감소 | GET 응답에 Cache-Control: max-age=3600 |
| 통일된 인터페이스 | 표준화된 리소스 상호작용 | 예측 가능하고 배우기 쉬운 API 표면 | GET /users/42, DELETE /users/42 |
| 계층화 시스템 | 클라이언트는 서버에 직접 말하는지 알 수 없음 | CDN, 게이트웨이, 로드 밸런서 삽입 가능 | 클라이언트 → CDN → API 게이트웨이 → 앱 서버 |
| 코드 온 디맨드(선택) | 서버가 실행 코드를 보내 클라이언트를 확장 | 필요할 때 클라이언트 기능 확장 | JavaScript 위젯 조각을 반환하는 API |
이 제약들이 실제 시스템에서 어떻게 맞물려 도는지 보려면, 아래 계층형 아키텍처를 떠올려 보세요.
클라이언트 / 모바일 앱
↓
CDN / 엣지 캐시 (예: Cloudflare)
↓
API 게이트웨이 (속도 제한, 인증, CORS)
↓
로드 밸런서
↓
애플리케이션 서버
↓
데이터베이스 / 내부 서비스
클라이언트는 CDN 계층하고만 이야기해요. 그 뒤에 계층이 몇 개나 더 있는지는 알지 못하죠. 이게 바로 계층화 시스템 제약이 실제로 작동하는 모습이고, 보안·캐싱·확장이 클라이언트 몰래 처리되는 지점이기도 하죠.
이제 하나씩 뜯어볼게요.
REST API 특성, 하나씩 풀어서 보기
클라이언트-서버 분리
Fielding의 첫 제약은 클라이언트(사용자가 직접 만지는 부분)와 서버(데이터와 로직이 사는 부분)를 반드시 떼어 놓으라는 거예요. 그는 이걸 관심사의 분리라고 불렀어요.
실무에서 왜 중요할까요? 모바일 뱅킹 앱 화면이 통째로 바뀌어도, 은행이 계좌 DB나 거래 엔진을 손댈 필요가 없다는 뜻이거든요. 예를 들어 Salesforce Marketing Cloud REST API는 연락처, 캠페인, 여정, 푸시 알림을 리소스 엔드포인트로 내줘요. 맞춤 대시보드를 짜든, 모바일 앱을 만들든, 외부 도구를 붙이든 백엔드는 그대로예요.
비즈니스 팀 입장에선 반복 작업이 빨라진다는 의미예요. 프런트엔드 디자이너와 백엔드 엔지니어가 같은 릴리스 주기에 묶이지 않거든요. API 계약만 흔들리지 않으면 양쪽은 따로 움직일 수 있어요.
무상태성
요청 사이에 기억이 없다는 뜻이에요. 클라이언트가 서버로 보내는 모든 호출은 그 요청을 처리하는 데 필요한 정보를 전부 담고 있어야 하고, 서버는 이전 대화의 흔적을 남기지 않아요.
저는 이걸 고객센터에 전화할 때마다 같은 사정을 처음부터 다시 설명하는 상황에 빗대요. 답답하긴 하죠. 그런데 장점이 큽니다. 손이 빈 아무 상담원이나 응대할 수 있고, 콜센터는 구조를 안 바꾸고도 상담원을 500명 더 붙일 수 있어요. 이게 수평 확장이에요.
기술적으로 보면 무상태성은 sticky session이 없다는 뜻이에요. 로드 밸런서는 다음 요청을 멀쩡한 아무 서버에나 던질 수 있어요. 한 서버가 죽어도 다른 서버가 자연스럽게 이어받죠. Fielding 논문은 무상태성이 가시성(모니터링 도구가 요청을 개별로 이해), 신뢰성(장애가 공유 세션을 망가뜨리지 않음), 확장성(서버가 요청 사이에 자원을 비움)을 높인다고 명시해요.
현실적 단서도 있어요. 실제 시스템엔 인증 토큰, 장바구니, OAuth 흐름이 있죠. 핵심은 어떤 상태도 어디에도 없다가 아니에요. 서버가 자기 메모리 안에 클라이언트 세션을 요청 사이에 들고 있지 않는다는 거죠. 그 역할은 토큰, 데이터베이스, 공유 캐시가 대신 맡아요.
캐시 가능성
"이 응답을 다시 써도 될까?" 이 질문에 답하는 게 캐시 가능성이에요. 응답은 자신이 캐시 가능한지 표시해야 하고, 가능하다면 클라이언트와 중간 계층(CDN 같은)이 다음에 똑같은 요청에 그걸 재사용해요. 서버 부하는 줄고 속도는 올라가죠.
HTTP 장치는 단순해요. Cache-Control, ETag, Last-Modified, Expires 같은 헤더가 응답이 얼마나 유효한지, 언제 다시 확인할지 알려줘요. 비즈니스 관점에선 응답마다 "이 답은 한 시간 동안 유효함" 또는 "매번 새로 확인하세요" 같은 라벨이 붙어 있다고 보면 돼요.
성능 효과도 분명해요. Cloudflare의 Regional Tiered Cache 실험에선 꼬리 지연 구간의 캐시 적중 응답 시간이 50~100ms 빨라졌다고 보고했어요. Fielding 논문도 웹 트래픽이 1994년 하루 10만 요청에서 1999년 하루 6억 요청으로 폭증하는 흐름을 기록하며, 캐싱이 핵심 설계 요소였다고 설명해요.
보통 캐시하는 것: 제품 카탈로그, 공개 블로그 글, 국가/통화 목록, API 문서
보통 캐시 안 하는 것: 개인 대시보드, 결제 총액, 은행 잔액, 관리자 보고서
통일된 인터페이스
Fielding 본인이 REST를 다른 스타일과 구분 짓는 핵심 특징이라 부른 제약이에요. 클라이언트가 리소스를 다루는 방식을 표준화해서 API를 예측 가능하게 만들죠.
이 아래엔 네 가지 하위 제약이 있어요.
- 리소스 식별: 모든 리소스는 안정적인 URI를 가져야 해요.
/customers/123은 고객,/orders/456은 주문이죠. - 표현을 통한 조작: 클라이언트는 서버 내부 객체가 아니라 리소스의 표현(JSON, XML, HTML)을 다뤄요.
- 자기 서술적 메시지: 요청과 응답엔 메서드, 상태 코드, 콘텐츠 타입, 오류 정보 같은 메타데이터가 충분히 들어 있어서, 중간자나 클라이언트가 내용을 이해할 수 있어야 해요.
- HATEOAS(Hypermedia as the Engine of Application State): 응답에 관련 작업과 리소스로 이어지는 링크를 담아, 클라이언트가 엔드포인트를 일일이 하드코딩하지 않고도 다음 행동을 찾아낼 수 있게 해요.
HTTP 메서드 매핑은 통일된 인터페이스에서 가장 눈에 띄는 부분이에요.
| HTTP 메서드 | CRUD 의미 | 안전한가? | 멱등성 있는가? | 예시 |
|---|---|---|---|---|
| GET | 읽기 | 예 | 예 | GET /products/42 |
| POST | 생성 / 동작 | 아니요 | 아니요 | POST /orders |
| PUT | 전체 리소스 교체 | 아니요 | 예 | PUT /users/42 |
| PATCH | 부분 업데이트 | 아니요 | 보장되지 않음 | PATCH /users/42 |
| DELETE | 삭제 | 아니요 | 예 | DELETE /sessions/abc |
Google Cloud의 HTTP 가이드라인은 GET은 안전해야 하고, GET·PUT·DELETE는 멱등적이어야 한다고 못 박아요. GitHub, Stripe, Spotify 같은 유명 API도 이 패턴을 따르니, 하나만 익혀 두면 다른 것도 금방 손에 익죠.
계층화 시스템
클라이언트는 자기가 지금 원본 서버와 말하는지, CDN 캐시인지, API 게이트웨이인지, 로드 밸런서인지 알 수 없어요. 바로 그게 핵심이에요. 각 구성 요소는 자기 옆 계층만 보거든요.
이 구조 덕에 가능한 것들이에요.
- CDN: Cloudflare처럼 API 앞단에서 응답을 캐시하고 가속
- API 게이트웨이: AWS API Gateway, Kong, Apigee 같은 도구가 인증·속도 제한·할당량 처리
- 로드 밸런서: 무상태 요청을 여러 앱 서버로 분산
Postman 2025 보고서에 따르면 조직의 47%가 AWS API Gateway를, 26%는 Azure 게이트웨이를, 31%는 여러 게이트웨이를 동시에 써요. 계층화 아키텍처는 이론이 아니라 실제 운영 시스템이 돌아가는 방식이에요.
물론 계층마다 약간의 지연이 붙어요. 하지만 Fielding은 대부분의 현실 시스템에서 중간 계층의 공유 캐싱이 그 오버헤드를 충분히 메운다고 봤어요.
코드 온 디맨드(선택 사항)
이건 좀 별난 제약이에요. 코드 온 디맨드는 REST에서 유일한 선택 항목으로, 서버가 JavaScript 같은 실행 코드를 보내 클라이언트 기능을 그 자리에서 늘릴 수 있게 해요.
현실에서 가장 흔한 예는 웹 페이지가 서버에서 JavaScript를 받아 오는 형태예요. 하지만 모바일 앱, 백엔드 작업, 자동화 도구가 쓰는 평범한 JSON REST API에선 거의 안 보여요. API 클라이언트는 원격 서버에서 온 임의 코드를 실행하고 싶어 하지 않거든요.
대부분의 독자에겐 이 제약이 각주 정도예요. Fielding 모델에 완전성을 위해 들어가 있지만, 일상적인 API 평가에서 비중이 크진 않아요.
많은 사람이 잘못 이해하는 것: 대부분의 REST API는 정말 RESTful할까요?
다들 대놓고 말하긴 꺼리는 사실이 있어요. 스스로 "RESTful"이라 부르는 실무 API 대부분은 사실 REST식 관행을 흉내 낸 HTTP JSON API에 가까워요. 리소스 URL, HTTP 메서드, 상태 코드를 쓰긴 하지만 딱 거기까지죠. r/softwarearchitecture의 한 스레드에선 개발자들이 Fielding 기준을 전부 채운 진짜 REST API를 만든 적 없다고 인정했어요. 또 다른 r/learnprogramming 토론에선 "RESTful"이 정확히 무슨 뜻인지조차 합의가 되느냐를 두고 갑론을박이 벌어졌고요.
2026년 한 연구에서 REST API 전문가 16명을 인터뷰했더니, 가이드라인이 사용성을 높이긴 하지만 개발자들은 엄격한 REST 규칙에 꽤 반발했어요. 가이드라인이 방대하고, 조직별 상황에 잘 안 맞는다는 게 이유였죠.
그렇다면 실제 현장에선 제약들이 어디까지 지켜질까요?
| 제약 | 실무 적용 수준 | 이유 |
|---|---|---|
| 클라이언트-서버 | ✅ 거의 보편적 | 웹 아키텍처의 기본이므로 피하기 어려움 |
| 무상태성 | ✅ 거의 보편적 | 수평 확장에 필요하고, 표준 관행임 |
| 통일된 인터페이스(기본) | ✅ 흔함 | 리소스 URI + HTTP 동사는 기본 패턴 |
| 캐시 가능성 | ⚠️ 일관되지 않음 | 많은 팀이 Cache-Control 헤더를 아예 생략함 |
| 계층화 시스템 | ⚠️ 암묵적 | CDN과 게이트웨이는 존재하지만 의도적으로 설계되지 않는 경우도 많음 |
| HATEOAS | ❌ 드묾 | 대부분의 클라이언트는 엔드포인트를 하드코딩하며, 링크 기반 탐색은 복잡성을 더함 |
| 코드 온 디맨드 | ❌ 매우 드묾 | 정의상 선택 사항이고, JSON API에서는 거의 구현되지 않음 |
팀들이 HATEOAS를 건너뛰는 이유: 클라이언트 개발자들은 런타임에 링크를 따라가느니, OpenAPI 문서를 읽고 SDK를 쓰는 쪽을 좋아해요. HATEOAS를 구현하려면 안정적인 미디어 타입, 링크 관계 정의, 워크플로 모델링이 필요해요. 당장의 비용은 큰데, 대부분의 팀에겐 돌아올 이득이 불분명하죠.
실용적인 결론은 이래요. API가 Fielding 규격을 100% 못 채워도 충분히 쓸모 있을 수 있어요. 다만 어떤 제약을 빼먹었고, 그 대가로 뭘 포기했는지 아는 건 더 나은 설계와 통합 결정에 도움이 돼요.
Richardson 성숙도 모델: 내 API는 실제로 얼마나 RESTful할까?
"REST냐 아니냐"라는 이분법이 별 도움이 안 된다면, Richardson 성숙도 모델이 더 실용적인 틀을 줘요. Leonard Richardson이 제안하고 Martin Fowler가 설명한 이 모델은 REST 채택 수준을 네 단계로 나눠요.
| 단계 | 이름 | 설명 | 실제 예시 |
|---|---|---|---|
| 0 | POX의 늪 | 단일 URI, 단일 HTTP 동사(보통 POST) | 레거시 SOAP-over-HTTP 엔드포인트; POST /api에 { "action": "getUser" } |
| 1 | 리소스 | 여러 URI(리소스별 1개)는 있지만 여전히 주로 POST 사용 | POST /users/123/getProfile, POST /orders/456/cancel |
| 2 | HTTP 동사 | GET, POST, PUT, DELETE를 올바르게 사용 + 적절한 상태 코드 | 오늘날 대부분의 실무 "REST" API |
| 3 | 하이퍼미디어(HATEOAS) | 응답에 관련 작업/리소스로 연결되는 링크 포함 | Spring Data REST, HAL 기반 API; 실제 공개 API에서는 매우 드묾 |
현장에서 마주치는 API 대부분은 2단계에 있어요. 리소스, 동사, 상태 코드를 제대로 쓰죠. 이것만으로도 충분히 실용적이고, 상호운용되고, 도구 지원도 잘 받아요. 3단계는 Fielding이 그린 완전한 그림이지만, 실제 채택은 여전히 적어요.
내 API는 어디쯤일까요? 스스로 이렇게 물어보세요.
- 모든 걸 처리하는 단일 엔드포인트 하나뿐인가요? (0단계)
- 비즈니스 객체마다 고유 URI가 있나요? (1단계 이상)
- HTTP 메서드와 상태 코드를 제대로 쓰나요? (2단계)
- 응답이 외부 문서 없이도 다음에 할 수 있는 일을 알려주나요? (3단계)
이 모델은 "REST냐 아니냐" 논쟁을 정리하는 데 제가 찾은 도구 중 가장 쓸모 있어요. 이분법을 스펙트럼으로 바꿔 주거든요.
흔한 REST API 실수와 피하는 방법
서드파티 API를 붙이는 일을 워낙 오래 하다 보니, 이젠 반복해서 마주치는 불만 목록이 생겼어요. 개발자 포럼을 보면 저만 그런 것도 아니고요. 자주 보이는 안티패턴을 모아 봤는데, 하나하나가 REST 제약 위반과 곧장 연결돼요.
| 안티패턴 | REST를 깨는 이유 | 대신 이렇게 하세요 |
|---|---|---|---|
| HTTP 200에 오류 본문({ "error": "잘못된 사용자 이름" }) | 자기 서술적 메시지를 위반해 클라이언트가 상태 코드를 신뢰할 수 없음 | 적절한 4xx/5xx 코드 + 구조화된 오류 본문 사용(예: application/problem+json) |
| 모든 것에 POST 사용 | 통일된 인터페이스를 무시하고 안전성/멱등성 의미를 잃음 | CRUD를 GET/POST/PUT(PATCH)/DELETE에 매핑 |
| Cache-Control 헤더 없음 | 캐시 가능성 제약을 아예 낭비함 | 명시적인 캐시 지시문 설정 — 민감한 데이터는 no-store도 포함 |
| 모호한 오류 응답("409 오류") | 사람도 기계도 무엇이 잘못됐는지 알 수 없음 | 오류 유형, 사람이 읽을 메시지, 문서 링크 포함 |
| HTTPS 미적용 | 베어러 토큰과 API 키가 평문으로 전송됨 | 모든 구간에서 TLS 강제; Google APIs는 기본적으로 HTTPS만 사용 |
| 요청 본문에 버전 넣기 | 리소스 식별을 깨고, 게이트웨이와 캐시가 제대로 라우팅할 수 없음 | URI 경로 버전(/v1/) 또는 Accept 헤더 버전 사용 |
Zalando RESTful API Guidelines는 공식 HTTP 상태 코드를 요구하고, 오류 응답엔 Problem JSON을 권장해요. Adidas API Guidelines는 Problem Detail은 4xx/5xx에만 쓰고 2xx와 섞지 말라고 못 박고요. 학술적 취향이 아니라, 규모 있게 API를 굴리는 팀들의 실무 기준이에요.
r/learnprogramming의 한 스레드에선 어떤 개발자가 오류에도 늘 HTTP 200을 반환해도 되는지 진지하게 묻고 있었어요. 2026년에도 이런 질문이 끊이지 않는다는 것만 봐도, 이 안티패턴이 얼마나 끈질긴지 알 수 있죠.
REST vs SOAP vs GraphQL vs gRPC: REST API 특성 비교하기
REST를 단독으로 이해하는 것도 좋지만, 대안과 나란히 놓고 보면 훨씬 또렷해져요.
| 비교 항목 | REST | SOAP | GraphQL | gRPC |
|---|---|---|---|---|
| 프로토콜 / 전송 방식 | 아키텍처 스타일, 보통 HTTP 사용 | XML 기반 메시징 프로토콜; HTTP, SMTP 등 | 쿼리 언어/런타임, 보통 HTTP 위에서 동작 | HTTP/2 기반 RPC 프레임워크 |
| 데이터 형식 | 보통 JSON, 그 외 XML/HTML도 가능 | XML만 사용(WSDL 계약) | 쿼리 모양에 맞는 JSON | Protocol Buffers(이진) |
| 캐싱 | ✅ 잘 설계하면 HTTP 네이티브 캐싱 가능 | ❌ 복잡함; HTTP 캐시 친화적이지 않음 | ⚠️ 더 어려움(POST + 단일 엔드포인트 + 쿼리 변화) | ❌ HTTP 캐싱 중심이 아님 |
| 실시간 지원 | ❌ 폴링/웹훅 | ❌ 엔터프라이즈 메시징 패턴 | ✅ 구독(Subscriptions) | ✅ 스트리밍, 낮은 지연 시간 |
| 학습 곡선 | 낮음~중간 | 높음 | 중간 | 중간~높음 |
| 적합한 용도 | 공개 API, CRUD, 웹/모바일 연동 | 엔터프라이즈/레거시, 엄격한 계약, 규정 준수 | 복잡한 쿼리, 유연한 프런트엔드, 모바일 앱 | 마이크로서비스 간 통신, 내부 고성능 처리 |
Postman의 API 아키텍처 스타일 비교는 호환성, 데이터 형태, 작업 방식, 사용자 도구를 기준 삼아 고르라고 조언해요.
언제 무엇을 고를까:
- REST는 넓은 호환성, 단순한 CRUD, HTTP 캐싱이 필요할 때 강해요. 공개 API와 웹/모바일 연동의 사실상 기본값이죠.
- SOAP는 엄격한 계약, WS-Security 요건, 쉽게 못 갈아엎는 레거시 통합이 있는 엔터프라이즈 환경에서 여전히 쓸모 있어요.
- GraphQL은 프런트엔드가 유연한 중첩 쿼리를 원하고, 과도한 조회나 부족한 조회를 피하고 싶을 때 빛나요. 복잡한 모바일 앱에서 특히 흔하죠.
- gRPC는 브라우저 호환성보다 낮은 지연과 이진 직렬화가 더 중요한 내부 마이크로서비스 통신에 잘 맞아요.
실제 REST 예시로 Thunderbit의 Open API가 있어요. 단순한 POST 엔드포인트(/distill과 /extract), JSON 요청/응답 본문, 베어러 토큰 인증, 표준 HTTP 상태 코드(400, 401, 402, 408, 422, 429, 500, 502, 503, 504)를 써요. SOAP 계약이나 gRPC의 복잡성 없이도 실무 AI 제품에서 REST 특성이 어떻게 적용되는지 잘 보여주죠. HATEOAS를 뽐내는 예시는 아니지만, 비즈니스 팀과 개발자가 쉽게 붙일 수 있는 실용적인 2단계 API예요.
REST API 특성이 비즈니스 팀에 중요한 이유
영업, 운영, 이커머스 팀은 API 코드를 직접 짜진 않죠. 하지만 벤더를 고르고, 도구를 연결하고, 자동화 워크플로를 짤 때 REST API의 품질이 그 통합을 고통스럽게 할지 매끄럽게 할지를 좌우해요.
도구 통합: CRM이 마케팅 자동화 플랫폼과 동기화될 때, REST API 설계가 그 동기화를 안정적으로 만들지 불안하게 만들지를 결정해요. Salesforce Marketing Cloud REST API는 예측 가능한 리소스 엔드포인트로 연락처, 캠페인, 여정, 푸시 알림을 다뤄요. 이런 엔드포인트가 REST 관례를 잘 따르면 RevOps 팀은 우회 작업 없이 자동화를 짤 수 있죠.
이커머스 운영: Shopify의 fulfillment REST 리소스는 이행 주문, 추적 번호, 배송 상태를 다뤄요. 배송 앱과 이행 도구가 이 계층에 기대죠. API가 제대로 설계돼 있으면 — 적절한 상태 코드, 캐시 가능한 카탈로그 데이터, 명확한 오류 메시지 — 물류 파이프라인이 매끄럽게 돌아요. 그렇지 않으면 새벽 2시에 이유 모를 장애를 맞죠.
벤더 평가: 6가지 제약을 알면 실용적인 체크리스트가 생겨요.
- API가 표준 상태 코드를 쓰나요, 아니면 실패가 죄다 200 OK로 보이나요?
- 오류가 자동화 도구가 복구할 만큼 구체적인가요?
- 속도 제한, 페이지네이션, 인증 문서가 명확한가요?
- 흔한 응답을 캐시해 부하를 줄일 수 있나요?
데이터 추출과 자동화: Thunderbit 같은 도구는 REST 기반 아키텍처로, 비즈니스 사용자가 웹사이트·PDF·이미지에서 구조화된 데이터를 뽑아 Google Sheets, Airtable, Notion, Excel로 내보내게 해줘요. Thunderbit의 AI 웹 스크래퍼 Chrome 확장 프로그램은 클릭 두 번으로 끝나는 화면 뒤에서 복잡한 처리를 맡는데, 그 아래에선 무상태 요청, JSON 응답, 표준 오류 같은 REST 원칙이 통합 계층의 안정성을 받쳐 줘요.
짚고 갈 데이터가 하나 더 있어요. Postman 2025 보고서에 따르면 개발자의 24%만이 AI 에이전트를 염두에 두고 API를 설계하고, 51%는 AI 에이전트의 무단·과도한 API 호출을 걱정해요. 자동화와 AI 워크플로가 비즈니스 팀의 표준이 되면서, 예측 가능한 REST 패턴, 최소 권한 API 키, 속도 제한은 더 이상 개발자만의 문제가 아니라 운영 리스크 요인이 되고 있죠.
Thunderbit가 비즈니스 사용자를 위해 REST 원칙을 적용하는 방식
우리는 Thunderbit를 만들 때, 대부분의 사용자는 REST 명세를 읽어 본 적도 없고 그럴 필요도 없다고 전제했어요. 그런데도 Thunderbit를 쉽게 만드는 설계 선택들은 이 글에서 다룬 REST 특성에 뿌리를 두고 있어요.
실제 사용 흐름은 이래요.
- Chrome Web Store에서 Chrome 확장 프로그램을 깔고, 데이터를 뽑을 웹사이트·PDF·이미지를 열어요.
- **"AI 필드 제안"**을 누르면 Thunderbit의 AI가 페이지를 읽고 열 구조를 제안해요. 상품명, 가격, 이메일 등 페이지에 있는 무엇이든 들어갈 수 있죠.
- 필요하면 열을 손본 뒤 **"스크랩"**을 눌러요. Thunderbit가 페이지네이션, 하위 페이지, 동적 콘텐츠를 알아서 처리해요.
- 데이터를 Google Sheets, Airtable, Notion, CSV, Excel로 내보내요. 무료이고, 유료 장벽도 없어요.
개발자와 자동화 워크플로를 위해 Thunderbit의 Open API는 /distill(정제된 Markdown 추출)과 /extract(구조화된 데이터 추출)를 JSON 본문을 쓰는 REST 스타일 POST 엔드포인트와 표준 HTTP 오류 코드로 제공해요. Richardson 성숙도 모델로 보면 2단계예요. 리소스, 올바른 메서드, 의미 있는 상태 코드를 갖췄죠.
웹 스크래핑이나 데이터 추출을 더 넓게 살펴보고 있다면, AI 웹 스크래핑, 코딩 없이 웹 스크래핑하기, 웹 스크래핑이 실제로 무엇인지에 대한 더 깊은 가이드도 준비돼 있어요.
핵심 요약
- REST는 프로토콜이 아니라 아키텍처 스타일이에요. 클라이언트-서버, 무상태성, 캐시 가능성, 통일된 인터페이스, 계층화 시스템, 선택적 코드 온 디맨드 — 이 6가지 제약이 API 설계를 안내해요.
- 대부분의 "RESTful" API는 완전한 RESTful이 아니에요. 다수는 Richardson 2단계(리소스 + HTTP 동사 + 상태 코드)에 머물러요. HATEOAS와 코드 온 디맨드는 거의 구현되지 않죠.
- Richardson 성숙도 모델이 가장 좋은 자체 점검 도구예요. "REST냐 아니냐"라는 이분법을 실용적인 스펙트럼(0~3단계)으로 바꿔 줘요.
- 200 OK로 오류 돌려주기, 모든 것에 POST 쓰기, 캐시 헤더 빼먹기 같은 실수는 여전히 흔해요. 제약을 이해하면 이런 안티패턴을 잡아내고 고칠 수 있어요.
- REST vs SOAP vs GraphQL vs gRPC는 '뭐가 최고냐'가 아니라 '뭐에 맞느냐'의 문제예요. REST는 공개 API와 CRUD 연동에 강하고, GraphQL은 복잡한 프런트엔드에, gRPC는 내부 마이크로서비스에, SOAP는 엔터프라이즈/레거시에 어울려요.
- 비즈니스 팀도 벤더를 평가하고, 도구를 잇고, 자동화 워크플로를 짤 때 REST 특성을 알면 득을 봐요. Thunderbit 같은 도구는 REST 원칙을 적용해 기술 지식 없이도 데이터 추출을 쉽게 만들어 줘요.
자주 묻는 질문
REST API의 6가지 특성은 무엇인가요?
REST의 6가지 제약은 (1) 클라이언트-서버 분리, (2) 무상태성, (3) 캐시 가능성, (4) 통일된 인터페이스, (5) 계층화 시스템, (6) 코드 온 디맨드(선택)예요. Fielding의 원래 정의로는 앞의 5가지가 RESTful API로 인정받기 위한 필수 조건이에요.
REST와 RESTful의 차이는 무엇인가요?
REST는 Roy Fielding이 정의한 설계 제약의 묶음, 즉 아키텍처 스타일이에요. "RESTful"은 그 제약을 따르는 API를 뜻하고요. 실제로는 "RESTful"이라 불리는 많은 API가 리소스, HTTP 메서드, 상태 코드만 구현하고 HATEOAS와 코드 온 디맨드는 생략하는 식으로, 부분적으로만 따라요.
모든 REST API가 모든 REST 제약을 따르나요?
아니요. 대부분의 실무 API는 클라이언트-서버 분리, 무상태성, 기본적인 통일된 인터페이스(리소스 + HTTP 동사)를 따라요. 캐시 가능성과 계층화 시스템은 구현이 들쭉날쭉하죠. HATEOAS는 드물고, 코드 온 디맨드는 JSON API에서 거의 안 써요.
REST와 GraphQL의 차이는 무엇인가요?
REST는 여러 엔드포인트로 리소스를 드러내고, 표준 HTTP 메서드(GET, POST, PUT, DELETE)를 써요. GraphQL은 보통 단일 엔드포인트를 쓰며, 클라이언트가 쿼리에서 원하는 필드를 정확히 짚어요. REST는 HTTP 네이티브 캐싱이 더 강하고, GraphQL은 복잡하고 중첩된 데이터 요구에 더 유연하며 과도한 조회를 줄여 줘요.
HATEOAS는 무엇이고, 실제로 쓰는 사람이 있나요?
HATEOAS(Hypermedia as the Engine of Application State)는 API 응답에 다음 가능한 작업을 알려주는 링크가 담겨, 클라이언트가 엔드포인트를 일일이 하드코딩하지 않고도 API를 탐색할 수 있다는 뜻이에요. Fielding이 그린 REST의 핵심(Richardson 3단계)이지만, 실제로 이걸 구현한 공개 API는 매우 드물어요. 대부분의 팀은 2단계에서 멈추고 문서와 SDK에 기대죠.
AI 웹 스크래핑을 위해 Thunderbit 사용해 보기
AI 웹 스크래핑을 위해 Thunderbit 사용해 보기 Get Started Free
더 알아보기
