🚀 Spring Boot 중급 개발자를 위한 RESTful API 설계 및 Best Practices

✅ 서론: RESTful API란 무엇이며, 왜 중요할까?
✅ 본론: RESTful API 설계 원칙 및 Best Practices
✅ 결론: 유지보수성과 확장성을 고려한 RESTful API 설계

---

1️⃣ 서론: RESTful API란 무엇이며, 왜 중요할까?

🔹 RESTful API란?

REST(Representational State Transfer)는 웹에서 클라이언트와 서버 간 통신을 위한 아키텍처 스타일입니다.
RESTful API는 이 REST 원칙을 따르는 웹 API를 의미하며, 일반적으로 HTTP 프로토콜을 사용하여 데이터를 주고받습니다.

🔹 RESTful API의 주요 특징

✅ 클라이언트-서버 구조: 프론트엔드와 백엔드를 분리하여 확장성 증가
✅ 무상태성(Stateless): API 요청 간에 서버가 클라이언트 상태를 유지하지 않음
✅ 캐시 가능(Cacheable): API 응답을 캐시하여 성능 최적화 가능
✅ 일관된 인터페이스(Uniform Interface): URL을 통해 자원을 명확하게 식별
✅ 계층화된 시스템(Layered System): 보안, 로드 밸런싱 등 추가 가능

🔥 RESTful API를 올바르게 설계하면 확장성과 유지보수성이 뛰어난 시스템을 구축할 수 있습니다.
이제 RESTful API 설계의 Best Practices를 살펴보겠습니다.

---

2️⃣ 본론: RESTful API 설계 원칙 및 Best Practices

🔹 1. RESTful URL 설계 원칙

✅ 리소스를 명확하게 식별
📌 좋은 예제 (명사 기반 URL)

GET    /users          -> 모든 사용자 조회  
GET    /users/{id}     -> 특정 사용자 조회  
POST   /users          -> 새 사용자 생성  
PUT    /users/{id}     -> 사용자 정보 업데이트  
DELETE /users/{id}     -> 사용자 삭제

 

📌 나쁜 예제 (행위 기반 URL - 지양해야 함)

GET    /getUsers  
POST   /createUser  
DELETE /removeUser

🔥 RESTful API에서는 URL에 "행위(Verb)"를 포함하지 않고, HTTP 메서드(GET, POST, PUT, DELETE)를 활용해야 합니다.

✅ 계층적 관계 표현 (Nested Resource)

GET /users/{userId}/posts      -> 특정 사용자의 게시글 조회  
GET /users/{userId}/posts/{postId} -> 특정 게시글 조회

🔥 리소스 간 계층적 관계를 명확하게 나타내야 합니다.

---

🔹 2. HTTP 메서드 활용 Best Practices

📌 RESTful API에서 HTTP 메서드의 역할

메서드	역활
GET	리소스 조회
POST	리소스 생성
PUT	리소스 전체 업데이트
PATCH	리소스 부분 업데이트
DELETE	리소스 삭제

📌 잘못된 예제 (HTTP 메서드 오남용)

GET /deleteUser?id=1    ❌ 잘못된 DELETE 요청
POST /updateUser        ❌ PUT을 사용해야 함

🔥 행위(Verb)를 포함한 URL을 사용하지 말고, 적절한 HTTP 메서드를 활용해야 합니다.

---

🔹 3. RESTful API 응답 코드 Best Practices

📌 HTTP 상태 코드 표준화

상태 코드	의미
200 OK	성공 (GET, PUT, PATCH, DELETE 요청에 사용)
201 Created	새 리소스 생성 성공 (POST 요청에 사용)
204 No Content	요청 성공했으나 응답 본문 없음 (DELETE 요청)
400 Bad Request	잘못된 요청 (잘못된 입력값 등)
401 Unauthorized	인증 실패 (로그인 필요)
403 Forbidden	권한 없음
404 Not Found	리소스를 찾을 수 없음
500 Internal Server Error	서버 내부 오류

📌 응답 예제 (JSON 형태)

{
  "status": 200,
  "message": "Success",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  }
}

🔥 일관된 응답 형식을 유지하여 클라이언트가 쉽게 파싱할 수 있도록 해야 합니다.

---

🔹 4. 페이징 및 정렬 API 설계

📌 페이징 처리 예제

GET /users?page=1&size=10

📌 정렬 적용 예제

GET /users?sort=name,asc  
GET /users?sort=createdAt,desc

📌 Spring Boot에서 Pageable을 활용한 페이징 API

@GetMapping("/users")
public ResponseEntity<Page<User>> getUsers(Pageable pageable) {
    Page<User> users = userService.getAllUsers(pageable);
    return ResponseEntity.ok(users);
}

🔥 페이징과 정렬을 적용하면 성능 최적화 및 데이터 조회의 유연성이 증가합니다.

---

🔹 5. RESTful API의 보안 (Spring Security & JWT 적용)

📌 API 보안을 강화하는 방법 ✅ API 요청을 인증해야 할 경우 JWT (JSON Web Token) 활용
✅ CORS 설정을 적절히 적용하여 보안 강화
✅ 민감한 데이터(비밀번호 등)는 암호화하여 전송
✅ REST API 요청에서 CSRF 보호는 불필요 (무상태 API)

📌 JWT 인증 적용 예제

http
    .csrf().disable()
    .authorizeRequests()
    .requestMatchers("/api/auth/**").permitAll()
    .anyRequest().authenticated()
    .and()
    .sessionManagement()
    .sessionCreationPolicy(SessionCreationPolicy.STATELESS);

🔥 보안이 취약한 RESTful API는 해킹 위험이 크므로, 인증 및 접근 제어를 철저히 해야 합니다.

---

3️⃣ 결론: 유지보수성과 확장성을 고려한 RESTful API 설계

RESTful API는 단순히 데이터를 주고받는 인터페이스가 아니라,
확장성과 유지보수성을 고려한 설계가 필요합니다.

📌 RESTful API 설계의 핵심 Best Practices 요약

✅ 명확한 URL 구조 사용 (명사 기반, HTTP 메서드 활용)
✅ 일관된 HTTP 상태 코드 및 응답 포맷 유지
✅ 페이징 및 정렬을 통한 성능 최적화
✅ JWT 인증 및 보안 강화
✅ 오픈 API 문서화 (Swagger 활용)

📌 Swagger를 활용한 API 문서 자동화

implementation 'org.springdoc:springdoc-openapi-ui:1.6.14'

✅ API 문서화를 통해 개발자 간 협업을 원활하게 진행할 수 있습니다.