✅ RESTful API의 정의와 좋은 REST API 설계 원칙

✅ RESTful API의 정의와 좋은 REST API 설계 원칙

프론트엔드와 백엔드의 데이터를 주고받는 데 있어 RESTful API는 가장 널리 사용되는 방식입니다.
개발자 면접에서도 "RESTful API란 무엇인가?", "좋은 설계 원칙은 무엇인가?" 같은 질문은 필수적으로 등장합니다.
이번 글에서는 REST의 기본 개념, 좋은 API 설계 원칙, 실무 적용 사례까지 단계별로 정리하겠습니다.

---

📌 1. REST와 RESTful API란?

✅ REST란?

Representational State Transfer의 약자로,
자원을 URI로 표현하고 HTTP 메서드로 상태를 주고받는 아키텍처 스타일입니다.

✅ RESTful API란?

• REST 아키텍처 스타일을 따르는 웹 API를 의미합니다.
• 서버와 클라이언트가 상태를 공유하지 않고 독립적으로 작동합니다.

---

✅ REST 구성 요소

구성 요소 설명

자원(Resource)	데이터를 고유하게 식별하는 URI
행위(Verb)	HTTP 메서드(GET, POST, PUT, DELETE 등)
표현(Representation)	JSON, XML 등 자원의 상태를 전달하는 형식

---

📌 2. HTTP 메서드와 CRUD 매핑

메서드 목적 CRUD 예시

GET	자원 조회	Read	GET /users
POST	자원 생성	Create	POST /users
PUT	자원 전체 수정	Update	PUT /users/1
PATCH	자원 일부 수정	Update	PATCH /users/1
DELETE	자원 삭제	Delete	DELETE /users/1

---

📌 3. 좋은 RESTful API 설계 원칙

반응형

🔍 1) 직관적이고 일관된 URI 사용

• 리소스의 의미가 명확하게 드러나도록 설계합니다.
• 복수형 사용 권장: /user ❌ → /users ✅

잘못된 예시 올바른 예시

/getUsers	/users
/updateUser/1	/users/1

---

🔍 2) HTTP 상태 코드 활용

• 성공과 실패에 대해 적절한 상태 코드를 반환합니다.

상태 코드 의미 예시

200 OK	요청 성공	데이터 조회 성공
201 Created	자원 생성 성공	새 유저 등록 성공
400 Bad Request	잘못된 요청	필수 필드 누락
401 Unauthorized	인증 실패	유효하지 않은 토큰
404 Not Found	자원 없음	존재하지 않는 ID
500 Internal Server Error	서버 오류	DB 연결 실패

---

🔍 3) 자원의 상태를 HTTP 메서드로 표현

• 동사를 URI에 포함하지 않음

잘못된 예시 올바른 예시

/getUserInfo/1	/users/1
/deleteUser/1	/users/1

---

🔍 4) 계층적 구조로 설계

• 상위 자원과 하위 자원의 관계를 명확하게 표현합니다.

계층 구조 예시

상위 자원	/users
하위 자원	/users/1/posts

---

🔍 5) JSON 형식으로 응답

• 대부분의 클라이언트가 JSON 파싱에 최적화되어 있음

{
  "id": 1,
  "name": "John",
  "email": "john@example.com"
}

---

🔍 6) HATEOAS 적용 (Hypermedia as the Engine of Application State)

• 응답 데이터에 다음 동작을 유도하는 링크를 포함

{
  "id": 1,
  "name": "John",
  "links": {
    "self": "/users/1",
    "posts": "/users/1/posts"
  }
}

---

📌 4. 실무에서 겪은 문제와 해결

🧪 문제

• 사용자 정보 수정 API 호출 시 PUT으로 구현했으나, 일부 필드만 수정할 때도 전체 데이터를 요구함

✅ 해결

• PATCH 메서드로 변경하여 부분 수정 가능하도록 개선

✅ 예시 코드 (Express)

app.patch('/users/:id', (req, res) => {
  const { id } = req.params;
  const updates = req.body;
  // 부분 수정 로직
  res.status(200).json({ message: `User ${id} updated`, updates });
});

---

📌 5. RESTful API 설계 예시

🔍 유저 관리 API

기능 메서드 경로 설명

유저 목록 조회	GET	/users	모든 유저 조회
유저 상세 조회	GET	/users/{id}	특정 유저 조회
유저 생성	POST	/users	새 유저 등록
유저 수정	PATCH	/users/{id}	유저 정보 일부 수정
유저 삭제	DELETE	/users/{id}	유저 삭제

---

📌 6. RESTful API 설계 도구

도구 특징

Postman	API 테스트 및 문서화
Swagger	API 문서 자동 생성
Insomnia	Postman 대안으로, 직관적인 UI 제공

---

📌 면접에서 이렇게 답하세요

RESTful API는 리소스를 URI로 표현하고, HTTP 메서드를 이용하여 상태를 주고받는 아키텍처입니다.
API 설계 시 직관적이고 일관성 있는 URI, 적절한 상태 코드 사용, 계층적 구조 유지가 중요합니다.
실무에서는 PATCH를 사용하여 부분 수정을 구현하고, JSON 형식으로 데이터를 응답하여 클라이언트에서 쉽게 파싱할 수 있도록 했습니다.
또한, Postman을 이용하여 API 테스트를 진행하며, 문제 발생 시 상태 코드와 응답 메시지로 디버깅을 쉽게 했습니다.

---

RESTfulAPI,API설계,HTTP메서드,ExpressAPI,REST설계원칙,API디자인,RESTAPI테스트,프론트엔드면접,백엔드연동,API베스트프랙티스