RESTful API, 말은 많이 들었는데 대체 뭘까?

 

 

개발을 조금만 해보다 보면 자연스럽게 접하게 되는 단어가 있습니다.

바로 REST API, 그리고 RESTful API.

 

많은 개발자들이

“REST API 제공해요”,

“RESTful하게 만들었어요”

라고 하지만 실제로는 두 개념이 많이 다르고, 많은 경우 혼용해서 쓰입니다.

 

 

REST API 가 뭘까?

REST란?

REpresentational State Transfer의 줄임말로,

웹의 자원(데이터)을 HTTP 프로토콜을 통해 일정한 규칙(표현) 으로 주고받는 구조입니다.

 

즉, REST는 서버와 클라이언트가 데이터를 주고받을 때

“이렇게 하면 서로 이해하기 쉽고 깔끔하게 동작할 수 있어요”

라는 설계 철학에 가까운 개념입니다.

 

그럼 REST API는?

REST의 철학을 바탕으로 만든 API (데이터 요청/응답 인터페이스)입니다.

 

HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용하고,

URI로 **자원(resource)**을 표현하며, 요청 방식에 따라 서버가 알맞게 동작하도록 만들어져 있습니다.

GET /users         → 모든 사용자 조회  
POST /users        → 사용자 생성  
GET /users/1       → ID가 1인 사용자 조회  
PUT /users/1       → ID가 1인 사용자 정보 수정  
DELETE /users/1    → ID가 1인 사용자 삭제

 

위처럼 명확한 규칙과 일관된 URI 구조로 구성된 API를 REST API라고 부릅니다.

그러나 대부분의 REST API 는 GET 또는 POST 만 사용하고 엔드포인트의 이름으로 구분하여 제작을 하죠.

 

하지만… 여기서 한 가지 중요한 질문!

 

이렇게 만들었다고 해서 진짜 RESTful한 걸까요?

그 기준은 어디서부터 어디까지일까요?

 

이제 그 답을 알기 위해, RESTful API가 진짜 의미하는 바를 알아보겠습니다.

 

 

 

RESTful API의 진짜 의미

REST API가 형식적인 규칙을 따르는 것이라면,

RESTful API는 REST의 철학과 원칙을 깊이 있게 반영한 설계 방식입니다.

 

즉, 단순히 HTTP 메서드만 썼다고 RESTful한 것이 아니라,

 

URL은 자원(Resource)을 나타내야 하고

클라이언트와 서버는 역할이 분리되어야 하며

상태는 요청에 다 담겨야 하고

서버는 확장성과 유연성을 갖춰야 하며

구조적으로 일관된 방식으로 이루어져야

비로소 RESTful하다고 말할 수 있습니다.

 

 

정리하자면..

RESTful하다는 건 REST의 원칙을 얼마나 충실히 지켰는가의 정도를 나타내는 말입니다.

 

그렇다면 이 RESTful한 설계를 만들기 위해서는

어떤 원칙을 지켜야 할까요?

 

 

 

 

 

REST의 6가지 제약조건

1. 클라이언트-서버 구조 (Client-Server)

사용자(클라이언트)와 데이터 처리 주체(서버)를 명확히 분리해야 합니다.

 

• 클라이언트는 UI, 사용자 입력 처리 등만 담당
• 서버는 데이터 저장, 비즈니스 로직 수행

실무 포인트
API 설계 시, 프론트엔드와 백엔드의 역할이 겹치지 않도록 API는 오직 데이터만 제공하도록 구성해야 합니다.

 

 

 

2. 무상태성 (Stateless)

서버는 요청 간의 상태 정보를 절대 저장하지 않아야 합니다.

 

• 모든 요청은 독립적이어야 함
• 클라이언트 상태는 요청 안에 전부 포함되어야 함 (ex. 토큰)

실무 포인트
세션 대신 JWT 토큰을 사용하고, 요청마다 필요한 인증 정보를 담도록 설계합니다.

 

 

 

3. 캐시 처리 가능 (Cacheable)

응답은 캐시 가능해야 하며, 클라이언트가 이를 재사용할 수 있어야 합니다.

 

• 응답에 Cache-Control 같은 메타데이터를 포함
• 자주 조회되는 데이터는 클라이언트/프록시에서 캐싱 가능

실무 포인트
리스트형 조회 API에는 max-age나 ETag 설정을 통해 응답 속도를 최적화합니다.

 

 

 

 

4. 계층화 시스템 (Layered System)

클라이언트는 중간 서버(프록시, 게이트웨이 등)의 존재를 알 필요 없이 요청해야 합니다.

 

• API Gateway, 인증 서버, 로드밸런서 등이 계층 역할
• 각 계층은 역할만 분리되고 투명하게 처리되어야 함

실무 포인트
API 서버 앞단에 인증 서버(NGINX + JWT)나 캐시 서버(Redis)를 두는 것도 REST 원칙에 부합한다.

 

 

 

 

5. 인터페이스 일관성 (Uniform Interface)

모든 API는 일관된 방식으로 작동해야 합니다.

 

• URI는 리소스를 명사로 표현 (예: /users/1)
• HTTP 메서드 사용 규칙 지킴 (GET, POST, PUT, DELETE 등)
• 응답 형식 일관 (보통 JSON)

실무 포인트

CRUD마다 정해진 URL, 메서드, 응답 구조(JSON 구조) 규칙을 팀 내에서 명확히 정해둡니다.

 

 

 

 

6. 코드 온 디맨드 (선택적) (Code on Demand)

필요할 경우, 서버는 클라이언트에 스크립트나 코드를 전송할 수 있습니다.

 

• 흔히 사용되지 않지만, HTML/JS 등을 클라이언트에 전송해 동작하게 할 수 있음

실무 포인트
이 항목은 선택사항이므로 대부분의 RESTful API 설계에서는 고려하지 않아도 무방합니다.

 

 

 

 

 

마무리

RESTful API는 단순히 URL에 /api를 붙이는 게 아니라,

명확한 설계 철학과 일관된 규칙을 바탕으로 만들어져야 합니다.

 

처음엔 귀찮고 복잡해 보일 수 있지만,

한 번 구조가 잡히면 팀 개발, 문서화, 유지보수까지 훨씬 쉬워집니다.

 

 

🧩 다음 글에서는

RESTful API URI 설계 원칙 + 실전 예제를 다뤄볼 예정입니다.

많은 관심 부탁드립니다!

 

오늘도 방문 해 주셔서 감사합니다.