[Web] REST API, RESTful API 개념

WEB

REST API, RESTful API 개념과 차이

목차

• 1. API
• 2. REST
• 3. REST API vs RESTful API
• 4. REST API 설계 방법
• 5. HTTP 상태 코드도 중요하다
• 6. 마치며

백엔드 공부를 시작하면 가장 먼저 마주치는 단어, REST API. 근데 RESTful API는 또 뭔가? 같은 건가 다른 건가? 오늘 한 번에 정리해보자.

1. API

REST API를 이해하려면 먼저 API가 뭔지 알아야 한다. API(Application Programming Interface)란, 서로 다른 소프트웨어가 서로 통신할 수 있도록 정해놓은 인터페이스다.

 

쉽게 말하면, 클라이언트(프론트엔드, 앱 등)가 서버에게 “이 데이터 줘” 하고 요청하고, 서버가 “여기 있어” 하고 응답하는 그 창구가 바로 API다.

프론트엔드와 백엔드가 데이터를 주고받는 연결 지점이 바로 API다.

2. REST

REST(Representational State Transfer)는 웹 통신을 위한 아키텍처 스타일(설계 원칙)이다. 2000년에 로이 필딩(Roy Fielding)이 그의 박사 논문에서 처음 정의했다.

 

REST 자체는 프로토콜이나 표준이 아니다. “이런 방식으로 설계하면 좋다”는 가이드라인에 가깝다. REST가 제시하는 핵심 원칙은 다음과 같다.

원칙	설명
클라이언트-서버 구조	클라이언트와 서버는 역할을 분리한다
무상태(Stateless)	각 요청은 독립적이며 서버는 클라이언트 상태를 저장하지 않는다
캐시 가능(Cacheable)	응답은 캐시될 수 있어야 한다
계층화 시스템	중간 서버를 거치는지 여부를 클라이언트가 알 필요 없다
일관된 인터페이스	URI와 HTTP 메서드 등 일관된 방식으로 통신한다
코드 온 디맨드 (선택)	필요하면 서버가 실행 가능한 코드를 전달할 수 있다

우리가 평소에 자주 접하는 카카오맵 API, 네이버 로그인, 공공데이터포털 등도 모두 REST API 방식으로 제공된다. 즉, 이미 우리 주변에서 널리 쓰이고 있는 방식이다.

이 원칙들을 잘 지키며 설계된 API가 바로 REST API다.

3. REST API vs RESTful API

솔직히 말하면 실무에서는 두 단어를 혼용해서 쓰는 경우가 대부분이다. 하지만 엄밀하게 구분하면 차이가 있다.

	REST API	RESTful API
의미	REST 원칙을 기반으로 만든 API	REST 원칙을 충실히 지킨 API
뉘앙스	REST 스타일을 따른다고 주장하는 API	REST 6가지 원칙을 제대로 준수한 API
현실	원칙 일부만 지켜도 REST API라고 부름	완전한 준수가 기준

즉, 모든 RESTful API는 REST API지만, 모든 REST API가 RESTful한 것은 아니다. 로이 필딩 본인도 “대부분의 REST API는 사실 RESTful하지 않다”고 말할 정도로, 완전한 RESTful 설계는 생각보다 까다롭다.

4. REST API 설계 방법

REST API는 URI + HTTP 메서드 조합으로 행위를 표현한다. 먼저 아키텍처부터 살펴보자.

아키텍처

클라이언트(웹 앱, 모바일 앱, 프론트엔드)가 HTTP 요청(GET, POST, PUT, DELETE)을 인터넷을 통해 서버로 전송하고, 서버는 API 엔드포인트에서 요청을 받아 비즈니스 로직을 처리한 뒤 HTTP 상태 코드와 JSON 데이터를 응답으로 돌려주는 REST API의 전체 흐름이다.

 

REST API는 데이터의 생성(Create), 조회(Read), 수정(Update), 삭제(Delete), 즉 CRUD를 HTTP 메서드로 표현한다.

HTTP 메서드

메서드	역할
GET	데이터 조회
POST	데이터 생성
PUT	데이터 전체 수정
PATCH	데이터 일부 수정
DELETE	데이터 삭제

 

URI 설계 예시

게시판 API를 설계한다고 해보자.

GET    /posts         → 게시글 목록 조회
GET    /posts/{id}    → 특정 게시글 조회
POST   /posts         → 게시글 작성
PUT    /posts/{id}    → 게시글 전체 수정
PATCH  /posts/{id}    → 게시글 일부 수정
DELETE /posts/{id}    → 게시글 삭제

응답 예시 (JSON)

GET /posts/1 요청 시 서버가 돌려주는 응답은 보통 이런 형태다.

{
  "id": 1,
  "title": "REST API란 무엇인가",
  "content": "REST API는 ...",
  "createdAt": "2025-01-01"
}

응답 데이터는 주로 JSON 형식으로 주고받으며, 프론트엔드에서 이 데이터를 파싱해서 화면에 보여준다.

URI 설계 시 주의할 점

❌ /getPosts          → 동사 사용 금지
❌ /posts/delete/1    → URI에 행위를 넣지 않는다
❌ /Posts             → 대문자 사용 지양
❌ /posts/            → 마지막 슬래시(/) 사용 지양

✅ /posts
✅ /posts/{id}
✅ /posts/{postId}/comments

REST에서는 행위를 URI에 넣지 않고, HTTP 메서드로 표현하는 것이 핵심이다.

5. HTTP 상태 코드도 중요하다

REST API는 응답에 적절한 HTTP 상태 코드를 함께 보내야 한다. 단순히 200만 사용하는 것은 RESTful한 설계라고 보기 어렵다.

코드	의미	예시
200 OK	요청 성공	GET, PUT, PATCH 성공
201 Created	리소스 생성 성공	POST 성공
204 No Content	성공했지만 반환 데이터 없음	DELETE 성공
400 Bad Request	잘못된 요청	필수 파라미터 누락
401 Unauthorized	인증 필요	로그인 안 한 사용자
403 Forbidden	권한 없음	다른 사람 글 삭제 시도
404 Not Found	리소스 없음	존재하지 않는 게시글 조회
500 Internal Server Error	서버 오류	서버 내부 에러

6. 마치며

REST API는 단순히 HTTP로 데이터를 주고받는 것 그 이상이다. URI와 HTTP 메서드를 어떻게 조합하느냐, 상태 코드를 얼마나 의미 있게 사용하느냐에 따라 API의 완성도가 달라진다.

 

RESTful API는 그 원칙을 잘 지킨 API를 부르는 말이고, 현실에서는 두 단어가 혼용되는 경우가 많다는 것도 알아두면 좋다.

다음 글에서는 Spring Boot로 실제 REST API를 만들어보는 과정을 다뤄볼 예정이다.