REST API 제대로 설계하기 (멱등성 완벽 이해)

"URL에 동사를 쓰면 왜 안 되나요?"
협업하기 좋은 API, 그리고 네트워크 장애에도 안전한 API를 만드는 RESTful 설계의 핵심을 정리합니다.

1. 자원(Resource)과 행위(Verb)

REST의 핵심은 URL에는 명사(자원)를 쓰고, HTTP 메서드에는 동사(행위)를 담는 것입니다.

❌ POST /deleteUser/1
✅ DELETE /users/1

2. 멱등성(Idempotency)이 중요한 이유

멱등성이란 "여러 번 요청해도 서버 상태가 동일한가?"를 의미합니다.

• GET: 조회일 뿐이므로 여러 번 해도 상태가 변하지 않음 (멱등O)
• PUT: 같은 값으로 덮어쓰므로 여러 번 해도 상태가 같음 (멱등O)
• POST: 호출할 때마다 새로운 데이터가 생성됨 (멱등X)

💡 실무 노트

결제나 주문 API에서 멱등성을 고려하지 않으면 치명적입니다. 네트워크 순단 현상으로 브라우저가 자동으로 재시도했을 때 중복 결제가 발생할 수 있거든요.

팁: API 가이드를 작성할 때 각 메서드의 멱등성 여부를 고려해 보세요. 특히 POST 요청의 경우 서버에서 중복 방지 로직(Idempotency Key 등)을 추가하는 고민을 해보는 것이 좋습니다.