REST API란 무엇인가: 개념부터 실무적인 이해까지 다시 정리하기

웹 개발을 하다 보면 REST API라는 표현은 정말 자주 듣게 됩니다.

"이 API는 RESTful하게 설계했다"
"REST API를 만든다"
"요즘은 그냥 JSON API면 REST라고 부르기도 한다"

그런데 막상 조금 깊게 들어가 보면 생각보다 애매해집니다.

REST는 정확히 무엇인지
그냥 HTTP + JSON이면 REST API라고 불러도 되는지
왜 URL을 자원 중심으로 설계하라고 하는지
왜 메서드와 상태 코드 의미를 잘 지켜야 한다고 하는지

이 지점에서 개념이 흐려지기 쉽습니다.

그래서 이번 글에서는 REST API를 단순 유행어처럼 보지 않고, 왜 이런 개념이 나왔고 실제로 무엇을 지향하는지를 기본기부터 다시 정리해보겠습니다.

한눈에 보면

먼저 짧게 정리하면 이렇습니다.

REST는 웹의 구조와 잘 맞는 아키텍처 스타일입니다.
REST API는 보통 HTTP 위에서 자원(resource) 중심으로 설계된 API를 말합니다.
핵심은 URL만 예쁘게 만드는 것이 아니라, 자원을 식별하고 HTTP 의미를 일관되게 활용하는 데 있습니다.
엄밀한 의미의 REST와 실무에서 말하는 REST API 사이에는 약간의 간극이 있습니다.
실무에서는 "완벽한 REST 순수주의"보다, HTTP 의미를 잘 살린 일관된 자원 중심 API가 더 중요할 때가 많습니다.

즉, REST API를 이해한다는 것은 단순히 /users 같은 URL 패턴을 외우는 것이 아니라, 웹에서 자원을 어떻게 다루고 표현할지에 대한 설계 관점을 이해하는 것에 가깝습니다.

먼저 REST는 무엇일까?

REST는 Representational State Transfer의 약자입니다.

이 이름만 보면 오히려 더 어렵게 느껴집니다. 실제로 처음 접하면:

"Representation이 뭐지?"
"State는 무슨 상태를 말하는 거지?"
"Transfer는 데이터를 보내는 거랑 뭐가 다른 거지?"

같은 질문이 생기기 쉽습니다.

그래서 처음에는 이름보다 방향을 먼저 잡는 편이 좋습니다.

REST는 웹을 설계할 때 잘 맞는 아키텍처 스타일입니다. 즉, "이렇게 설계하면 웹의 특성을 잘 살릴 수 있다"는 설계 원칙 묶음에 가깝습니다.

여기서 중요한 것은 REST가 특정 라이브러리나 프레임워크가 아니라는 점입니다.

REST는 Express가 아니고
Spring이 아니고
Next.js API Route도 아니며
JSON 자체도 아닙니다

즉, REST는 구현 기술보다 설계 방식에 가까운 개념입니다.

왜 REST가 등장했을까?

이걸 이해하면 REST를 훨씬 덜 기계적으로 보게 됩니다.

웹은 원래 문서와 자원을 연결하고 이동하는 구조에서 출발했습니다. 브라우저는 URL로 자원을 식별하고, HTTP 메서드와 상태 코드, 캐시와 링크 같은 공통 규약 위에서 동작합니다.

REST는 이런 웹의 기본 특성을 거스르지 않고, 웹이 원래 잘하는 방식 위에서 시스템을 설계하자는 생각에 가깝습니다.

즉, 새 규칙을 자꾸 만드는 대신:

자원은 URL로 식별하고
행위는 HTTP 메서드로 드러내고
응답은 상태 코드와 표현 형태로 전달하고
클라이언트와 서버는 느슨하게 결합되도록 하자

는 방향입니다.

그래서 REST를 이해할 때는 "API 설계 규칙"으로만 보기보다, 웹 자체의 철학을 API 설계에 가져온 것으로 보면 훨씬 자연스럽습니다.

REST API는 보통 무엇을 뜻할까?

실무에서 REST API라고 말할 때는 대개 HTTP 기반 API를 의미합니다.

그리고 보통 아래 성격을 기대합니다.

자원 중심 URL
HTTP 메서드 의미 활용
상태 코드 활용
stateless한 요청 처리
JSON 같은 표현 형식으로 자원 상태 전달

예를 들어:

GET /users/1
POST /users
PATCH /users/1
DELETE /users/1

이런 형태는 많은 사람이 REST API답다고 느낍니다.

왜냐하면:

users라는 자원이 있고
/1은 특정 자원을 식별하고
메서드가 조회/생성/수정/삭제 성격을 드러내기 때문입니다

즉, REST API는 보통 자원을 URL로 식별하고, HTTP 의미를 통해 자원 상태를 다루는 API를 말합니다.

여기서 resource는 정확히 무엇일까?

REST를 이해할 때 가장 중요한 단어 중 하나가 resource입니다.

resource는 단순히 "DB 테이블 한 줄"만을 의미하지는 않습니다. 조금 더 넓게 보면, 시스템이 식별하고 다룰 가치가 있는 대상이라고 볼 수 있습니다.

예를 들면:

사용자
게시글
댓글
주문
장바구니
상품 목록

같은 것들이 자원이 될 수 있습니다.

중요한 것은 자원이 꼭 내부 구현과 1:1로 대응할 필요는 없다는 점입니다.

예를 들어:

GET /me는 현재 로그인한 사용자라는 개념적 자원일 수 있고
GET /reports/sales-summary는 집계 결과라는 자원일 수 있고
GET /search?q=react는 검색 결과라는 자원 표현일 수 있습니다

즉, resource는 "테이블 이름"이 아니라, 클라이언트가 식별하고 접근할 수 있는 의미 있는 대상에 가깝습니다.

representation은 무엇일까?

Representational State Transfer라는 이름에서 representation도 중요한 단어입니다.

클라이언트가 받는 것은 자원 그 자체가 아니라, 그 자원의 표현 형태입니다.

예를 들어 사용자라는 자원이 있을 때:

브라우저 화면에서는 HTML로 표현할 수 있고
모바일 앱에서는 JSON으로 표현할 수 있고
내부 시스템에서는 XML이나 다른 포맷으로 표현할 수도 있습니다

즉, 클라이언트와 서버가 주고받는 것은 보통 "자원의 표현"입니다.

예를 들어:

{
  "id": 1,
  "name": "Marco",
  "role": "admin"
}

이 JSON은 사용자 그 자체가 아니라, 사용자 자원을 표현한 한 형태라고 볼 수 있습니다.

이 관점을 이해하면 REST를 단순 CRUD API보다 조금 더 넓게 볼 수 있습니다.

REST는 단순히 CRUD를 예쁘게 적는 규칙일까?

많은 경우 REST는 CRUD 문법처럼 소비됩니다.

GET: 조회
POST: 생성
PUT/PATCH: 수정
DELETE: 삭제

물론 이 매핑은 매우 중요합니다. 하지만 REST를 여기에만 가두면 개념이 너무 얕아집니다.

REST의 핵심은 단순히 CRUD를 나열하는 것이 아니라:

무엇이 자원인지 분명히 하고
그 자원을 어떻게 식별할지 정하고
자원의 상태를 어떤 표현으로 주고받을지 정하고
HTTP라는 공통 의미 체계를 최대한 활용하는 데 있습니다

즉, CRUD는 REST의 표면적인 모습 중 일부일 뿐이고, 더 본질적인 것은 자원 중심 사고와 웹 규약 활용입니다.

REST의 주요 제약은 무엇일까?

엄밀하게 REST를 이야기할 때는 여러 제약 조건이 함께 나옵니다. 실무에서 모두를 완벽하게 외울 필요는 없지만, 큰 방향은 알고 있는 편이 좋습니다.

1. Client-Server

클라이언트와 서버의 관심사를 분리합니다.

클라이언트는 UI와 사용자 경험에 집중하고
서버는 데이터와 비즈니스 로직 처리에 집중합니다

이 분리는 독립적인 개발과 변경을 쉽게 만듭니다.

2. Stateless

각 요청은 스스로 이해 가능해야 합니다.

서버는 이전 요청을 기본 전제로 기억하지 않고, 필요한 정보는 현재 요청 안에 담겨 있어야 합니다.

이 제약은 확장성과 운영 안정성에 매우 중요합니다.

3. Cacheable

응답은 캐시 가능 여부를 명시할 수 있어야 합니다.

웹은 원래 캐시를 잘 활용하도록 설계된 환경이기 때문에, REST 역시 캐시 가능성을 중요한 특성으로 봅니다.

4. Uniform Interface

REST를 REST답게 만드는 핵심 제약 중 하나입니다.

쉽게 말하면, 자원을 다루는 방식이 API마다 제각각이 아니라 어느 정도 일관된 인터페이스를 가져야 한다는 뜻입니다.

예를 들어:

자원은 URI로 식별하고
메서드는 공통 의미를 따르고
응답은 일관된 방식으로 자원 표현을 돌려주고
링크나 상태 전이를 예측 가능한 방식으로 다룹니다

즉, REST는 "각 API가 각자만의 규칙을 만드는 것"보다, 공통 의미를 공유하는 인터페이스를 중시합니다.

5. Layered System

클라이언트는 중간에 프록시, 게이트웨이, CDN 같은 계층이 있어도 그것을 꼭 알 필요는 없습니다.

이 제약 덕분에 웹은 중간 계층을 유연하게 끼워 넣을 수 있습니다.

6. Code on Demand

선택적 제약입니다.

서버가 클라이언트에 실행 가능한 코드를 내려주는 개념인데, 웹에서는 JavaScript를 통해 어느 정도 자연스럽게 떠올릴 수 있습니다. 다만 실무에서 REST API 설명의 핵심으로 자주 다뤄지지는 않습니다.

왜 Uniform Interface가 그렇게 중요할까?

실무에서 REST를 얘기할 때 많은 것이 결국 여기로 모입니다.

만약 API마다 규칙이 전부 다르면 어떤 일이 생길까요?

조회도 어떤 곳은 POST /getUser
수정도 어떤 곳은 POST /updateUser
삭제도 어떤 곳은 POST /deleteUser
응답 구조도 제각각
에러 처리도 제각각

이렇게 되면 클라이언트는 엔드포인트마다 새로운 규칙을 배워야 합니다.

즉, 시스템이 커질수록 API는 "사용하기 쉬운 도구"가 아니라 "암기해야 하는 예외 목록"이 됩니다.

반대로 REST가 지향하는 방향은:

자원은 URL로 드러내고
메서드는 공통 의미를 가지며
상태 코드는 익숙한 방식으로 해석되고
표현 구조도 일관되게 유지하는 것

입니다.

즉, Uniform Interface의 가치는 멋진 이론이 아니라, 시스템 규모가 커져도 API를 예측 가능하게 유지하는 데 있습니다.

그렇다면 그냥 HTTP + JSON이면 REST API일까?

이 질문이 정말 자주 나옵니다.

정답은 조금 애매하지만, 그래서 더 중요합니다.

엄밀하게 말하면 HTTP를 쓰고 JSON을 주고받는다고 해서 자동으로 REST가 되는 것은 아닙니다.

예를 들어:

POST /getUser
POST /updateUser
POST /deleteUser

처럼 모든 행위를 POST에 몰아넣고, URL이 전부 동사 중심이며, 상태 코드와 캐시 의미도 거의 활용하지 않는다면 HTTP를 쓰더라도 REST에 가깝다고 보기 어렵습니다.

반대로:

자원을 잘 식별하고
HTTP 메서드 의미를 지키고
상태 코드와 캐시 의미를 활용하고
stateless하게 요청을 처리한다면

그 API는 RESTful하다고 말하기 쉬워집니다.

즉, 중요한 것은 JSON이라는 포맷이 아니라, 웹의 공통 의미 체계를 얼마나 잘 활용하고 있는가입니다.

실무에서 말하는 REST API와 엄밀한 REST는 왜 다를까?

이 부분도 기본기에서 꼭 짚고 넘어갈 필요가 있습니다.

실무에서 "REST API"라고 하면 보통:

HTTP 기반이고
자원 중심 URL을 쓰며
JSON 응답을 주고
메서드와 상태 코드를 나름 잘 활용하는 API

를 말하는 경우가 많습니다.

하지만 엄밀한 REST는 더 넓고, 더 제약이 많고, 더 이상적인 개념입니다.

예를 들어 실제 현업에서는:

완전한 하이퍼미디어 제약까지 지키지 않거나
캐시를 제한적으로만 활용하거나
도메인 특성상 일부 엔드포인트가 RPC처럼 보일 수 있습니다

그렇다고 해서 그것이 무조건 "잘못된 API"인 것은 아닙니다.

즉, 실무에서는 종종 "REST 그 자체"보다 REST 철학을 얼마나 일관되게 반영했는가가 더 중요합니다.

하이퍼미디어까지 꼭 지켜야 REST일까?

엄밀한 REST를 공부하다 보면 HATEOAS 같은 개념을 만나게 됩니다.

핵심은 응답이 다음에 가능한 행동에 대한 링크나 전이 정보를 포함해, 클라이언트가 서버가 제공한 링크를 따라 상태를 이동할 수 있어야 한다는 방향입니다.

예를 들면:

{
  "id": 1,
  "status": "pending",
  "links": {
    "self": "/orders/1",
    "cancel": "/orders/1/cancel",
    "payment": "/orders/1/payment"
  }
}

이런 식의 구조를 떠올릴 수 있습니다.

실무에서는 이 수준까지 엄격하게 적용하지 않는 경우도 많습니다. 하지만 이 개념이 말해주는 방향은 중요합니다.

즉, REST는 단순히 데이터만 던지는 것이 아니라, 클라이언트가 다음 상태로 어떻게 이동할지도 표현할 수 있다는 관점을 갖고 있습니다.

REST API를 실무에서는 어떻게 이해하면 좋을까?

여기서부터가 정말 중요합니다.

실무에서 REST API를 이해할 때는 "교과서 정의"와 "현업 설계 감각"을 함께 가져가야 합니다.

1. REST API는 자원 중심 설계다

API를 만들 때 가장 먼저 "무슨 기능을 만들까?"보다 "우리가 다루는 자원은 무엇인가?"를 묻는 편이 좋습니다.

예를 들어:

유저 관리 기능
게시글 작성 기능
주문 처리 기능

이라고 생각하기보다:

사용자 자원
게시글 자원
주문 자원

으로 바라보는 것입니다.

이 관점이 잡히면 URL, 메서드, 응답 구조가 훨씬 덜 흔들립니다.

2. HTTP 의미를 억지로 무시하지 않는 설계다

RESTful한 API는 보통 이미 존재하는 HTTP 의미를 잘 활용합니다.

조회는 GET
생성은 POST
전체 교체는 PUT
일부 수정은 PATCH
삭제는 DELETE

즉, 새로운 규칙을 계속 만들기보다 웹이 원래 갖고 있는 언어를 그대로 활용하는 설계입니다.

3. 클라이언트가 예측 가능한 API다

좋은 REST API는 문서를 보기 전에도 어느 정도 예상이 됩니다.

예를 들어:

/users는 사용자 목록이나 생성
/users/1은 특정 사용자 조회/수정/삭제
/users/1/posts는 그 사용자의 게시글 목록

같은 흐름이 자연스럽게 읽혀야 합니다.

즉, 좋은 REST API는 "설명해야만 쓸 수 있는 API"보다 보고도 어느 정도 감이 오는 API에 가깝습니다.

4. 완벽주의보다 일관성이 중요하다

현실의 서비스는 늘 교과서처럼 깔끔하지 않습니다.

검색 API
파일 업로드
결제 승인
복잡한 배치 작업 시작

같은 경우는 순수한 CRUD로만 보기 어려울 수 있습니다.

이때 중요한 것은 "절대적으로 완벽한 REST인가?"만 따지는 것이 아니라, 전체 시스템 안에서 의미와 규칙이 얼마나 일관적인가입니다.

REST API가 아닌 설계는 어떤 느낌일까?

비교해 보면 감이 더 잘 옵니다.

예를 들어 아래는 RPC에 더 가까운 느낌입니다.

POST /createUser
POST /updateUser
POST /deleteUser
POST /getUserDetail

이 방식은 기능 이름은 분명하지만, HTTP가 제공하는 공통 의미를 많이 활용하지 못합니다.

반대로 아래는 자원 중심에 더 가깝습니다.

GET /users/1
POST /users
PATCH /users/1
DELETE /users/1

이쪽은:

URL이 자원을 드러내고
메서드가 행위를 드러내고
상태 코드를 활용하기 쉽고
캐시와 멱등성 같은 HTTP 특성도 연결하기 쉬워집니다

즉, REST API는 단순히 예쁜 주소 체계가 아니라, HTTP와 잘 맞는 방식으로 자원을 다루는 설계라고 이해하는 편이 좋습니다.

프론트엔드와 백엔드는 REST API를 어떻게 다르게 체감할까?

둘 다 같은 API를 쓰지만 보는 포인트는 조금 다를 수 있습니다.

프론트엔드 입장

URL이 예측 가능해야 호출이 쉽고
상태 코드가 일관돼야 UI 분기가 쉬우며
응답 구조가 안정적이어야 상태 관리가 편해집니다

즉, 프론트엔드에게 REST API는 단지 호출 대상이 아니라 예측 가능한 계약입니다.

백엔드 입장

자원을 어떻게 식별할지
메서드와 상태 코드를 어떻게 매핑할지
캐시와 멱등성을 어떻게 살릴지
API가 시간이 지나도 일관성을 유지할 수 있을지

를 계속 고민해야 합니다.

즉, 백엔드에게 REST API는 단지 엔드포인트 목록이 아니라 도메인을 외부에 드러내는 인터페이스 설계입니다.

자주 하는 오해

REST API를 공부할 때 자주 생기는 오해를 정리하면 아래와 같습니다.

1. REST API는 그냥 JSON API다

아닙니다. JSON은 표현 형식일 뿐이고, REST의 핵심은 자원 중심 설계와 HTTP 의미 활용에 있습니다.

2. URL만 복수형으로 만들면 REST다

아닙니다. 메서드, 상태 코드, 캐시, stateless 같은 요소도 함께 봐야 합니다.

3. REST는 무조건 완벽하게 지켜야만 의미가 있다

아닙니다. 실무에서는 제약을 얼마나 일관되게 반영했는지가 더 중요할 때가 많습니다.

4. REST API는 백엔드만 알면 된다

아닙니다. 프론트엔드도 API 계약을 이해해야 좋은 호출 구조와 예외 처리, 캐시 전략을 만들 수 있습니다.

같이 보면 좋은 글

결론

REST API는 단순히 /users 같은 URL 규칙을 뜻하는 개념이 아닙니다. 더 본질적으로는 웹이 원래 잘하는 방식에 맞춰 자원을 식별하고, HTTP 의미를 활용해 시스템 간 계약을 설계하는 방식에 가깝습니다.

짧게 정리하면:

REST는 웹과 잘 맞는 아키텍처 스타일이고
REST API는 자원 중심으로 HTTP를 활용하는 API 설계이며
실무에서는 완벽한 순수성보다 일관된 의미와 예측 가능성이 더 중요합니다

결국 REST API를 제대로 이해한다는 것은 URL 패턴을 외우는 것이 아니라, 웹의 공통 언어를 어떻게 API 설계에 녹일지 이해하는 것에 더 가깝습니다.

카테고리

자주쓰는 태그

REST API란 무엇인가: 개념부터 실무적인 이해까지 다시 정리하기

한눈에 보면

먼저 REST는 무엇일까?

왜 REST가 등장했을까?

REST API는 보통 무엇을 뜻할까?

여기서 resource는 정확히 무엇일까?

representation은 무엇일까?

REST는 단순히 CRUD를 예쁘게 적는 규칙일까?

REST의 주요 제약은 무엇일까?

1. Client-Server

2. Stateless

3. Cacheable

4. Uniform Interface

5. Layered System

6. Code on Demand

왜 Uniform Interface가 그렇게 중요할까?

그렇다면 그냥 HTTP + JSON이면 REST API일까?

실무에서 말하는 REST API와 엄밀한 REST는 왜 다를까?

하이퍼미디어까지 꼭 지켜야 REST일까?

REST API를 실무에서는 어떻게 이해하면 좋을까?

1. REST API는 자원 중심 설계다

2. HTTP 의미를 억지로 무시하지 않는 설계다

3. 클라이언트가 예측 가능한 API다

4. 완벽주의보다 일관성이 중요하다

REST API가 아닌 설계는 어떤 느낌일까?

프론트엔드와 백엔드는 REST API를 어떻게 다르게 체감할까?

프론트엔드 입장

백엔드 입장

자주 하는 오해

1. REST API는 그냥 JSON API다

2. URL만 복수형으로 만들면 REST다

3. REST는 무조건 완벽하게 지켜야만 의미가 있다

4. REST API는 백엔드만 알면 된다

같이 보면 좋은 글

결론

Marco Lee@beta1360

태그

댓글