– 헷갈리기 쉬운 규칙 깔끔하게 정리해드립니다
RESTful API는 클라이언트와 서버 간 통신을 설계할 때
가장 널리 사용되는 방식입니다.
하지만 RESTful이 무엇인지 알고 있다고 해도,
실제 API를 설계하거나 URL을 작성할 때는
어떤 메서드를 어떤 자원에 적용해야 할지 헷갈리는 경우가 많습니다.
이번 포스팅에서는 RESTful API의 핵심 개념부터,
많이 혼동되는 URL 규칙과 메서드 사용 원칙까지 예시와 함께 정리해드리겠습니다.
초보 개발자 분들부터 실무자까지 참고하시기 좋은 내용입니다.
✅ RESTful API란?
REST는 Representational State Transfer의 줄임말로,
웹의 자원을 ‘일관된 방식으로 표현하고 조작하는 아키텍처 스타일입니다.
RESTful API는 이 개념을 기반으로 설계된 API입니다.
✅ RESTful 설계의 6가지 원칙
원칙 설명
| 1. 자원의 식별 | URL은 **자원(Resource)**을 명확히 나타내야 합니다 (/users, /products/1) |
| 2. 표현의 자체 완결성 | 서버는 클라이언트 요청에 대해 필요한 모든 정보를 포함해 응답해야 합니다 |
| 3. 상태 없음(Stateless) | 요청 간 서버에 상태를 저장하지 않습니다 (각 요청은 독립적) |
| 4. 캐시 가능 | 응답에 따라 클라이언트가 결과를 캐싱할 수 있도록 설계해야 합니다 |
| 5. 계층 구조 | API는 **중간 계층(프록시, 로드 밸런서 등)**을 통해 요청을 처리할 수 있어야 합니다 |
| 6. 일관된 인터페이스 | 통신 방식이 표준화되어 있어야 합니다 (URI + HTTP Method 조합) |
✅ RESTful에서 가장 중요한 2가지 핵심
- 자원 중심 설계 (URL은 명사형)
- HTTP 메서드에 따라 행위 구분 (GET, POST, PUT, DELETE 등)
✅ RESTful API에서 자주 헷갈리는 규칙 TOP 5
1️⃣ URL에는 동사를 넣지 않습니다 ❌
잘못된 예 올바른 예
| /getUsers, /createUser | /users + GET, /users + POST |
URL은 자원을 표현하는 “명사”만 사용해야 하며,
동작은 HTTP 메서드로 구분합니다.
2️⃣ 복수형 명사를 사용해야 합니다
잘못된 예 올바른 예
| /user/1 | /users/1 |
| /product | /products |
REST는 “컬렉션(자원 목록)” 개념을 사용하기 때문에 복수형이 원칙입니다.
3️⃣ 하위 자원은 URL 경로로 표현합니다
목적 RESTful 방식
| 특정 사용자의 주문 조회 | /users/1/orders |
| 특정 게시글의 댓글 | /posts/99/comments |
계층적 관계는 URL에 반영해야 의미가 분명해집니다.
4️⃣ GET 요청에는 절대로 리소스를 생성하지 않습니다
❌ 잘못된 방식 ✅ 올바른 방식
| GET /create-user?name=Tom | POST /users (body에 JSON 포함) |
GET은 조회 전용입니다. 서버 상태를 변경하면 안 됩니다.
5️⃣ 응답은 항상 상태 코드와 함께 처리해야 합니다
상태 HTTP 코드
| 정상 조회 | 200 OK |
| 생성 완료 | 201 Created |
| 삭제 성공 | 204 No Content |
| 잘못된 요청 | 400 Bad Request |
| 인증 필요 | 401 Unauthorized |
| 서버 에러 | 500 Internal Server Error |
클라이언트는 상태 코드만으로도 결과를 파악할 수 있어야 합니다.
✅ RESTful 설계 예시 정리 (자주 쓰는 API 설계)
기능 URL 메서드
| 사용자 목록 조회 | /users | GET |
| 사용자 등록 | /users | POST |
| 특정 사용자 조회 | /users/{id} | GET |
| 사용자 정보 수정 | /users/{id} | PUT or PATCH |
| 사용자 삭제 | /users/{id} | DELETE |
| 사용자 댓글 조회 | /users/{id}/comments | GET |
RESTful API 설계는 처음엔 어렵게 느껴지지만,
명확한 기준과 규칙을 기억하고, HTTP 메서드와 URL을 일관되게 적용한다면
개발자뿐 아니라 클라이언트, 협업자 모두가 이해하기 쉬운 API를 만들 수 있습니다.
특히 백엔드 개발자에게 RESTful 원칙은 코드 품질뿐 아니라 협업 효율을 좌우하는 기준이 되기 때문에
기본 개념부터 헷갈리는 규칙까지 확실히 정리해두시면 실무에서 큰 도움이 됩니다.