REST API 설계 기본 원칙 정리 (백엔드 개발자를 위한 가이드)

REST API 설계 기본 원칙 정리 (백엔드 개발자를 위한 가이드)

백엔드 개발을 하다 보면 반드시 접하게 되는 개념이 바로 REST API입니다.

하지만 처음 API를 설계할 때 이런 고민을 하게 됩니다.

• URL을 어떻게 설계해야 할까?
• GET, POST, PUT은 언제 사용해야 할까?
• RESTful한 API는 어떤 구조일까?

이번 글에서는 REST API 설계 기본 원칙을 실제 개발에서 사용하는 방식으로 정리해 보겠습니다.

---

목차

• REST API란 무엇인가
• REST API 설계 핵심 원칙
• HTTP Method 올바른 사용
• RESTful URL 설계 규칙
• 응답 구조 설계
• 정리

---

REST API란 무엇인가

REST API는 웹에서 데이터를 주고받기 위한 아키텍처 스타일입니다.

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

쉽게 말하면

HTTP 프로토콜을 기반으로 자원을 표현하고 처리하는 방식입니다.

예를 들어 사용자 정보를 조회하는 API라면 다음과 같이 설계할 수 있습니다.

GET /users/1

이 요청은 다음 의미를 가집니다.

• users → 사용자 자원
• 1 → 특정 사용자
• GET → 조회 요청

---

REST API 설계 핵심 원칙

REST API 설계에서 가장 중요한 것은 자원을 중심으로 설계하는 것입니다.

즉 API는 동작이 아니라 리소스 중심으로 설계해야 합니다.

좋지 않은 예

/getUser
/createUser
/deleteUser

REST 방식

GET /users
POST /users
DELETE /users/1

이렇게 하면 API 구조가 훨씬 명확해집니다.

---

HTTP Method 올바른 사용

REST API에서는 HTTP Method를 명확하게 사용하는 것이 중요합니다.

Method	설명	예시
GET	데이터 조회	/users
POST	데이터 생성	/users
PUT	전체 수정	/users/1
PATCH	부분 수정	/users/1
DELETE	데이터 삭제	/users/1

이 규칙을 지키면 API 사용자가 훨씬 쉽게 이해할 수 있습니다.

---

RESTful URL 설계 규칙

좋은 REST API는 URL만 봐도 어떤 API인지 이해할 수 있어야 합니다.

REST URL 설계 기본 규칙은 다음과 같습니다.

• 명사를 사용한다
• 복수형을 사용한다
• 동사를 사용하지 않는다
• 계층 구조를 표현한다

예시

GET /users
GET /users/1
GET /users/1/orders

이 URL만 봐도 의미를 쉽게 이해할 수 있습니다.

---

응답 구조 설계

REST API에서는 응답 구조도 일정하게 유지하는 것이 좋습니다.

예시 JSON 응답

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Lee"
  }
}

에러 응답 예시

{
  "success": false,
  "message": "User not found"
}

이렇게 응답 구조를 통일하면 프론트엔드 개발도 훨씬 편해집니다.

---

정리

REST API 설계 핵심 원칙을 정리하면 다음과 같습니다.

• 자원(Resource) 중심 설계
• HTTP Method 올바르게 사용
• URL은 명사 중심으로 작성
• 응답 구조 통일

이 원칙만 잘 지켜도 대부분의 REST API 설계를 안정적으로 할 수 있습니다.

실제 프로젝트에서는 여기에

• API 버전 관리
• 인증 방식
• 에러 코드 관리

같은 요소들이 추가됩니다.

---

자주 묻는 질문 (FAQ)

REST API와 RESTful API는 다른 개념인가요?

REST API는 REST 스타일을 사용하는 API이고, RESTful API는 REST 원칙을 잘 지킨 API를 의미합니다.

REST API에서 POST와 PUT 차이는 무엇인가요?

POST는 새로운 데이터를 생성할 때 사용하고 PUT은 기존 데이터를 전체 수정할 때 사용합니다.

REST API 설계에서 가장 중요한 것은 무엇인가요?

자원을 중심으로 설계하는 것입니다.