REST API 개념과 예시 (스프링부트)

REST API란?

REST(Representational State Transfer)는 네트워크를 통해 자원을 효율적으로 관리하고 제공하기 위한 아키텍처 스타일입니다.

즉, REST API란 REST 원칙을 따르는 API를 말합니다.

API 개념과 원리

 

REST API의 핵심 특징

• 자원(Resource) 중심 구조 (ex. /users, /products)
• 각 자원은 **URI(Uniform Resource Identifier)**로 식별
• 상태가 없는(Stateless) 특성
• HTTP 메소드를 통해 자원에 접근 및 조작
• 일반적으로 데이터 포맷은 JSON을 주로 사용 (XML 등도 가능)

---

HTTP 메소드(HTTP Method)란?

HTTP 메소드는 웹에서 클라이언트와 서버 간의 요청(Request)의 유형을 정의합니다.

 

대표적 HTTP 메소드 종류 및 설명

메소드	설명	예시
GET	자원을 조회	GET /users
POST	자원을 생성	POST /users
PUT	자원을 전체 수정	PUT /users/{id}
PATCH	자원을 부분 수정	PATCH /users/{id}
DELETE	자원을 삭제	DELETE /users/{id}

---

HTTP 상태 코드(HTTP Status Code)란?

HTTP 요청에 대한 응답(Response)으로, 요청의 결과를 나타내는 코드입니다.

대표적 상태 코드 예시

• 2xx (성공)
  • 200: OK (성공)
  • 201: Created (자원 생성 성공)
• 3xx (리다이렉션)
  • 301: Moved Permanently (영구적으로 이동됨)
• 4xx (클라이언트 오류)
  • 400: Bad Request (잘못된 요청)
  • 401: Unauthorized (인증 실패)
  • 403: Forbidden (권한 부족)
  • 404: Not Found (자원 없음)
• 5xx (서버 오류)
  • 500: Internal Server Error (내부 서버 오류)
  • 503: Service Unavailable (서비스 사용 불가)

---

REST API 설계 규칙 예시

좋은 REST API 설계는 다음 규칙을 준수합니다.

• 자원 중심의 URI 설계
• 동사는 URI에 포함하지 않음 (메소드가 대신 역할)
• 버전 관리를 명확히 함 (ex. /api/v1/users)
• 직관적이고 예측 가능한 구조 유지

올바른 예시

GET    /users          → 사용자 목록 조회
GET    /users/{id}     → 특정 사용자 조회
POST   /users          → 사용자 생성
PUT    /users/{id}     → 특정 사용자 전체 수정
DELETE /users/{id}     → 특정 사용자 삭제

잘못된 예시 (안티패턴)

GET /getUsers          → (동사 사용 X)
POST /updateUser       → (POST는 생성에 사용, 업데이트는 PUT 또는 PATCH 사용 권장)

---

Spring Boot에서의 REST API 예시 (Gradle 기준)

Gradle 의존성 추가

implementation 'org.springframework.boot:spring-boot-starter-web'

간단한 컨트롤러 예시

@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // 사용자 조회 로직
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        // 사용자 생성 로직
    }

    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody User user) {
        // 사용자 수정 로직
    }

    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) {
        // 사용자 삭제 로직
    }
}

---

REST API를 설계하고 구현한 후에는 반드시 API 명세서를 작성해야 합니다. 명세서는 API가 어떻게 동작하는지, 클라이언트가 어떻게 사용해야 하는지를 명확하게 정의한 문서입니다.

---

API 명세서의 주요 구성요소

API 명세서는 최소한 다음 내용을 포함해야 합니다.

• API 이름과 목적
• API 호출 URL 및 메소드
• 파라미터 설명 (필수 여부 포함)
• 응답(Response) 데이터 형식
• 상태 코드 및 예외 처리 방식
• 요청 예시(Request Example) 및 응답 예시(Response Example)

---

실제 API 명세서 작성 예시 (실무 스타일)

사용자 조회 API 명세 예시

항목	설명
메소드	GET
URL	/api/v1/users/{id}
설명	특정 사용자 정보를 조회합니다.
Path Parameter	id(Long, 필수): 사용자 ID
요청 헤더	Authorization: 인증 토큰 (필수)
성공 응답	상태코드: 200 OK Body: 사용자 정보
실패 응답	상태코드: 404 Not Found Body: 오류 메시지

요청 예시

GET /api/v1/users/1 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbG...
Accept: application/json

성공 응답 예시

{
  "id": 1,
  "name": "홍길동",
  "email": "hong@example.com"
}

실패 응답 예시

{
  "status": 404,
  "message": "사용자를 찾을 수 없습니다."
}

---

API 명세서를 작성하는 이유

• 팀원 간의 명확한 의사소통
• 프론트엔드와 백엔드 개발 간 협업 용이
• 테스트 및 유지보수 간편
• 신규 멤버 온보딩 효율 향상