REST API, 개념부터 설계 원칙까지 한 번에 이해하기

현대적인 웹 애플리케이션 개발에서 백엔드와 프론트엔드, 또는 여러 서비스 간의 통신은 대부분 REST API를 통해 이루어집니다. "RESTful하다"는 말을 자주 들어보셨겠지만, 정확히 무엇을 의미하고 어떻게 설계해야 하는지 명확하게 이해하는 것은 중요합니다.

이번 포스팅에서는 백엔드 개발자가 어떻게 REST API를 '설계하고 만드는지', 그리고 프론트엔드 개발자가 **fetch**를 통해 이 API를 어떻게 **'사용하는지'**에 대한 전체적인 그림을 그려보겠습니다. 🌐

---

## 1. REST API란 무엇인가?

**REST(Representational State Transfer)**는 웹의 분산 시스템을 위한 아키텍처 스타일이며, 이 스타일을 따르는 API를 REST API라고 부릅니다.

간단히 말해, REST API는 URI를 통해 **자원(Resource)**을 명시하고, HTTP Method를 통해 해당 자원에 대한 CRUD 오퍼레이션을 적용하는 방식입니다.

### 핵심 개념

• 자원 (Resource): 회원 정보, 게시글 등 API가 다루는 모든 데이터. 고유한 URI로 식별됩니다. (참고: 우리가 웹에서 사용하는 주소는 대부분 URL이며, URL은 URI의 한 종류입니다.)
• 행위 (Verb / Method): POST, GET, PUT, DELETE 등 자원에 대한 행위를 나타내는 HTTP 메소드.
• 표현 (Representation): 자원을 주고받는 데이터 형식. 주로 JSON을 사용합니다.

### 백엔드와 프론트엔드의 역할

• 백엔드 개발자: 위의 3가지 핵심 개념을 바탕으로, API를 설계하고 서버에 구현합니다. (예: Spring Boot로 @RestController 작성)
• 프론트엔드 개발자: 만들어진 API를 호출하여 사용합니다. JavaScript의 fetch와 같은 도구를 사용하여 서버에 데이터를 요청하고, 받은 JSON 데이터를 화면에 표시합니다.

---

## 2. RESTful API 설계 원칙

좋은 REST API, 즉 'RESTful'한 API를 만들기 위한 핵심 원칙들은 다음과 같습니다.

1. 자원은 URI로, 행위는 HTTP Method로: URI에는 getMembers 같은 동사가 아닌 /members 같은 명사를 사용하고, 행위는 GET, POST 등으로 표현합니다.
2. 무상태성 (Stateless): 서버는 클라이언트의 상태를 저장하지 않습니다. 각 요청은 그 자체로 완전해야 합니다.
3. 자체 표현 구조 (Self-Descriptive): 요청/응답 메시지만으로도 그 의도를 명확히 알 수 있어야 합니다. (HTTP 상태 코드 등을 적극 활용)

---

## 3. HTTP 상태 코드 활용

요청의 결과를 명확하게 알려주기 위해 적절한 HTTP 상태 코드(Status Code)를 사용하는 것이 중요합니다.

코드	이름	설명
200	OK	요청 성공
201	Created	자원 생성 성공 (POST 응답)
204	No Content	성공했으나 응답 본문 없음 (DELETE 응답)
400	Bad Request	클라이언트의 요청이 잘못됨
404	Not Found	요청한 자원을 찾을 수 없음
500	Internal Server Error	서버 내부 오류 발생

Sheets로 내보내기

---

## 4. REST API와 fetch 사용 예시 (게시글)

백엔드가 /api/posts라는 API를 만들어두면, 프론트엔드에서는 fetch를 사용하여 다음과 같이 통신합니다.

### 게시글 생성 (Create)

• Backend API: POST /api/posts
• Frontend fetch 호출:

JavaScript

 

fetch('/api/posts', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ title: '새 게시글', content: '내용입니다.' })
});

### 전체 게시글 조회 (Read)

• Backend API: GET /api/posts
• Frontend fetch 호출:

JavaScript

 

fetch('/api/posts')
    .then(response => response.json())
    .then(posts => console.log(posts));

### 특정 게시글 수정 (Update)

• Backend API: PUT /api/posts/1
• Frontend fetch 호출:

JavaScript

 

fetch('/api/posts/1', {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ title: '수정된 제목', content: '수정된 내용' })
});

### 특정 게시글 삭제 (Delete)

• Backend API: DELETE /api/posts/1
• Frontend fetch 호출:

JavaScript

 

fetch('/api/posts/1', {
    method: 'DELETE'
});

---

## 5. 결론

REST API는 웹 서비스 간의 효율적이고 표준화된 통신을 가능하게 하는 강력한 아키텍처 스타일입니다. 위에서 설명한 원칙들을 잘 지켜 설계한다면, 확장성, 유연성, 그리고 유지보수성이 뛰어난 백엔드 시스템을 구축할 수 있습니다.

결국 REST API는 백엔드와 프론트엔드가 원활하게 협업하기 위한 가장 중요한 **'소통의 약속'**입니다.