[Spring] RESTful API

✅ REST란?

REST (Representational State Transfer)

• 자원을 URI로 표현하고
• HTTP Method로 행위(조회, 생성, 수정, 삭제)를 명확하게 구분해 API를 설계하는 방식
• 웹의 기본 구조(HTTP 프로토콜)에 가장 잘 맞는 설계 방식

 

✅ RESTful API란?

REST 원칙을 지키며 만든 API → 직관적이고, 이해하기 쉬운 API 디자인

🌱 RESTful API 기본 구조

[HTTP Method] + [URI] → 의미 있는 하나의 행위

행위	HTTP Method	예시 URI	의미
조회 (Read)	GET	/users	유저 목록 조회
상세 조회	GET	/users/1	id=1인 유저 조회
생성 (Create)	POST	/users	새 유저 생성
수정 (Update)	PUT / PATCH	/users/1	id=1인 유저 수정
삭제 (Delete)	DELETE	/users/1	id=1인 유저 삭제

 

✅ RESTful API 설계 핵심 원칙

1. URI는 리소스(Resource)를 나타낸다
   • 명사로 작성 (동사 ❌)
   • 예시: /users, /articles, /comments
2. 행위는 HTTP Method로 표현한다
   • GET, POST, PUT, DELETE, PATCH 등
3. 복수형 사용 권장
   • /user ❌ → /users ✅
4. 계층적 구조로 설계
   • 예시: /users/1/comments → 1번 유저의 댓글 목록
5. 상태 코드로 결과를 명확하게 알려준다
   • 200 OK, 201 Created, 204 No Content, 400 Bad Request 등

 

✅ RESTful API 설계 예시 - 게시판 서비스

 

📌 1. 게시글 전체 조회

  

    
    
    
    
  
GET /posts
→ 게시글 목록을 가져온다

 

응답 예시 (JSON)

  

    
    
    
    
  
[
  { "id": 1, "title": "첫 번째 글" },
  { "id": 2, "title": "두 번째 글" }
]

 

 

📌 2. 게시글 상세 조회

  

    
    
    
    
  
GET /posts/1
→ id=1인 게시글 상세 조회

 

 

📌 3. 게시글 작성

  

    
    
    
    
  
POST /posts
→ 게시글 생성

 

요청 Body (JSON)

 

  

    
    
    
    
  
{
  "title": "새 글 제목",
  "content": "글 내용입니다."
}

 

 

📌 4. 게시글 수정

  

    
    
    
    
  
PUT /posts/1
→ id=1인 게시글 수정

 

요청 Body (JSON)

  

    
    
    
    
  
{
  "title": "수정된 제목",
  "content": "수정된 내용"
}

 

 

📌 5. 게시글 삭제

  

    
    
    
    
  
DELETE /posts/1
→ id=1인 게시글 삭제

 

 

✅ RESTful API 장점

✔ URL만 봐도 어떤 작업을 하는지 명확하게 이해 가능
✔ 클라이언트, 서버 역할 분리로 유지보수 용이
✔ 확장성 좋고 표준화되어 API 문서화가 쉬움
✔ HTTP 구조 그대로 사용 → 성능 최적화 가능

 

✅ RESTful 설계 시 주의점

❌ POST /createPost, GET /getUserInfo → ❌ 잘못된 설계 (동사 사용 금지)
✅ POST /posts, GET /users/1 → ✅ 리소스 중심 설계

 

✅ RESTful API 실무 포인트

• 설계할 때 리소스 명확하게 구분하고
• 상태 코드 제대로 반환하기 (201, 204, 400, 404, 500 등)
• 필요하다면 쿼리 파라미터로 검색 조건 추가

  

    
    
    
    
  
GET /posts?title=스프링&author=홍길동

 

🎯 핵심 정리

✔ RESTful API란 HTTP 프로토콜과 가장 잘 맞는 설계 방식
✔ URI로 리소스를 표현하고, HTTP Method로 행위 구분
✔ 클린하고 유지보수 쉬운 API의 기본 설계 원칙

 

 

✅ REST API 성숙도 모델 4단계 (RMM 0 ~ 3 단계)

API가 RESTful해지는 수준을 0단계부터 3단계까지로 나누어 설명

단계	특징	설명
0단계	RPC 수준	- 모든 요청을 POST로 처리 - URL은 전부 /api/doSomething 형태 - HTTP 개념 활용 거의 없음
1단계	리소스 도입	- 리소스 개념 도입 (/users, /posts) - 하지만 Method는 여전히 POST로만 처리
2단계	HTTP Method 사용	- GET, POST, PUT, DELETE 제대로 사용 - REST의 핵심에 가까워짐
3단계	HATEOAS	- 응답 안에 '다음 행동'에 대한 링크 포함 - 진정한 RESTful (거의 사용 X)

 

✅ 각 단계 상세 예시

📌 0단계 - 그냥 HTTP로 만든 API

  

    
    
    
    
  
POST /api
Body: {
  "action": "getUser",
  "userId": 1
}

• 행위도 Body로 전달
• HTTP Method 의미 없음
• 완전한 RPC 방식

 

📌 1단계 - 리소스 URL만 도입

  

    
    
    
    
  
POST /users
Body: {
  "action": "getUser",
  "userId": 1
}

• /users 같은 리소스는 생겼지만
• 여전히 POST 하나로 모든 행동 처리

 

📌 2단계 - RESTful 핵심 도달

  

    
    
    
    
  
GET /users/1 → 유저 조회
POST /users → 유저 생성
PUT /users/1 → 유저 전체 수정
PATCH /users/1 → 유저 일부 수정
DELETE /users/1 → 유저 삭제

✔ HTTP Method로 행동 표현
✔ 리소스 중심 설계

 

📌 3단계 - HATEOAS (Hypermedia As The Engine Of Application State)

  

    
    
    
    
  
GET /users/1
Response:
{
  "id": 1,
  "name": "홍길동",
  "links": [
    { "rel": "self", "href": "/users/1" },
    { "rel": "update", "href": "/users/1" },
    { "rel": "delete", "href": "/users/1" }
  ]
}

• 응답 안에 '다음 행동 링크' 제공
• 클라이언트는 링크만 따라가면 됨
• 하지만 실무에서는 거의 사용되지 않음 (너무 복잡, 비용↑)

 

✅ 실무에서는 어디까지?

• 대부분의 API는 2단계면 충분히 RESTful
• 3단계 (HATEOAS) 는 대규모 시스템이나 대기업, 공공 API에서 일부 사용
• 현실적으로는 2단계 수준을 "RESTful API"로 부르며 개발

 

✅ RESTful API 설계시 참고 포인트

✔ 2단계 수준이면 대부분 OK (GET/POST/PUT/DELETE 정확히 사용)
✔ 응답에 필요한 데이터만 담고, 상태코드 정확히 반환하기
✔ HATEOAS는 개념만 이해하고, 실무에서 요구되지 않는다면 안 써도 된다

 

✅ 정리 - 성숙도 모델 핵심 포인트

단계	수준	비고
0단계	그냥 HTTP로 만든 API	REST 거의 없음
1단계	리소스 URL 도입	Method는 여전히 POST
2단계	진짜 RESTful	Method 분리 (GET, POST, PUT, DELETE)
3단계	완벽 REST (HATEOAS)	현실적으론 거의 안 씀