🌐 RESTful API 설계 원칙 정리하기!

RESTful API는 웹 서비스를 설계할 때 가장 널리 사용되는 아키텍처 스타일 중 하나입니다. "REST"는 Representational State Transfer의 약자로, 자원을 명확하고 일관된 방식으로 접근할 수 있도록 해주는 규칙을 말해요.

이번 포스트에서는 RESTful API를 설계할 때 지켜야 할 핵심 원칙들을 정리해볼게요.

✅ 1. 자원(Resource)은 명사로, URI는 단수 or 복수형

REST에서는 URI가 자원을 나타내야 해요. 즉, 무엇을 조작할지를 나타내는 거죠.

예시:

• ❌ GET /getUser
• ✅ GET /users/1

자원의 집합은 보통 복수형으로 표현해요.

동작	HTTP 요청	설명
전체 사용자 조회	GET /users	사용자 목록 반환
특정 사용자 조회	GET /users/1	ID가 1인 사용자 반환
사용자 생성	POST /users	새로운 사용자 생성
사용자 수정	PUT /users/1	ID가 1인 사용자 전체 수정
사용자 삭제	DELETE /users/1	ID가 1인 사용자 삭제

✅ 2. HTTP 메서드의 의미를 지켜야 함

메서드	용도
GET	데이터 조회 (읽기)
POST	데이터 생성
PUT	전체 수정
PATCH	부분 수정
DELETE	데이터 삭제

✅ 3. 계층적 구조로 URI 설계

자원 간의 관계가 있을 때는 URI 구조를 계층적으로 표현합니다.

• ✅ GET /users/1/posts : ID가 1인 사용자의 게시글 목록
• ✅ GET /users/1/posts/5 : ID가 1인 사용자의 게시글 중 ID가 5인 글

✅ 4. 응답은 상태 코드와 함께

상태 코드	의미
200 OK	요청 성공
201 Created	리소스 생성 성공
204 No Content	성공했지만 응답 바디 없음
400 Bad Request	잘못된 요청
401 Unauthorized	인증 실패
404 Not Found	리소스 없음
500 Internal Server Error	서버 오류

✅ 5. HATEOAS (Hypermedia As The Engine Of Application State)

응답 데이터 안에 다음 행동을 위한 링크를 제공하는 방식입니다.

{
  "id": 1,
  "name": "Alice",
  "links": [
    { "rel": "self", "href": "/users/1" },
    { "rel": "posts", "href": "/users/1/posts" }
  ]
}

🎯 꼭 필수는 아니지만 자동 탐색 가능한 API를 만들 때 유용합니다.

✅ 6. 무상태성 (Stateless)

REST는 무상태(stateless)를 기본 철학으로 해요. 서버는 클라이언트의 상태를 저장하지 않으며, 모든 요청은 독립적으로 처리되어야 해요.

즉, 클라이언트는 매 요청마다 필요한 정보를 모두 담아야 하고, 서버는 세션 정보를 기억하지 않음이 원칙입니다.

✅ 마무리 요약

• URI는 자원을 명사로 표현 (복수형 권장)
• 기능은 HTTP 메서드로 표현
• 자원 간 관계는 URI에 계층 구조로 표현
• 상태 코드를 명확히 사용
• HATEOAS는 선택 사항
• 서버는 무상태로 유지