RESTful이라는 단어는 이제 너무 흔하게 들리지만,
저는 그 안에서 실제 설계에 도움이 되는 기준이 무엇인지 항상 고민해왔습니다.
제가 중요하게 생각하는 RESTful의 핵심은 단 하나입니다.
"URI와 메서드만 보고도 이 API가 무슨 일을 하는지 직관적으로 파악할 수 있어야 한다."
1️⃣ URI에는 행위가 아닌 자원만 담긴다
REST는 기본적으로 자원(Resource) 중심의 설계입니다.
즉, URI에는 create, get, update, delete 같은 동사가 들어가선 안 된다고 생각합니다.
❌ /createUser, /deletePost/1
✅ /users, /posts/1
- URI는 명사, 행위는 HTTP 메서드가 담당합니다.
- URI만 봤을 때도 어떤 자원에 대한 작업인지 명확하게 드러나야 합니다.
2️⃣ HTTP 메서드는 역할에 충실하게
HTTP 메서드는 그 자체로 이미 의도를 담고 있는 표현 도구입니다.
| 메서드 | 의미 |
|---|---|
GET | 자원 조회 |
POST | 자원 생성 |
PUT | 자원 전체 수정 |
PATCH | 자원 일부 수정 |
DELETE | 자원 삭제 |
POST로 삭제 요청을 보내거나, GET으로 자원을 변경하는 API는 RESTful하지 않다고 생각합니다.
의도한 행위를 HTTP 메서드에 정확히 매핑하는 것은, 설계자의 책임입니다.
메서드 매핑 시, 흔히 하는 실수 모음!
3️⃣ URI는 자원의 구조와 범위를 명확하게 표현해야 한다
RESTful한 URI는 계층 구조가 분명해야 합니다.
예를 들어 사용자의 게시글에 접근하고 싶다면 이렇게 표현합니다:
/users/1/posts/42
- 어떤 유저의 어떤 게시글인지 명확하게 드러남
- 리소스 간의 포함 관계(계층)를 URI 에 구조적으로 반영
4️⃣ 서버 개발자는 항상 무상태성(stateless) 을 유의해야 한다
REST의 핵심 원칙 중 하나는 Stateless입니다.
즉, 서버는 클라이언트의 상태를 절대 기억하지 않는다는 것.
- 매 요청마다 필요한 정보는 클라이언트가 전송해야 하며
- 서버는 요청을 독립적으로 처리해야 합니다
이는 개발자로 하여금 예측 가능하고 확장 가능한 설계를 가능하게 만듭니다.
✍️ 마무리: 내가 생각하는 RESTful
RESTful한 API란 단지 규칙을 따르는 것이 아닙니다.
저는 "설계자의 의도를 명확하게 드러낼 수 있는 구조"를 갖춘 API가 RESTful하다고 생각합니다.
결국 RESTful이란, 좋은 API란 무엇인가에 대한 끊임없는 고민이라고 생각합니다.
