REST API 엔드포인트 설계의 핵심 원칙

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

웹 개발

대상자

REST API 설계에 관심 있는 개발자, 특히 초보자 및 중급 개발자 (난이도: 중간)

핵심 요약

• 엔드포인트는 동사가 아닌 명사 중심으로 설계해야 하며, 예: ❌ /getUserById → ✅ /users/:id
• 쿼리 파라미터를 활용해 필터링 및 조건 추가 (예: /users?withTasks=true)
• REST 원칙 준수로 API의 확장성과 유연성을 확보

섹션별 세부 요약

1. 문제점: 과도하게 복잡한 엔드포인트

• getUsersWithTasks와 같은 동사 기반 엔드포인트는 REST 원칙을 위반
• 복잡한 엔드포인트는 유지보수와 확장성에 부정적 영향
• 관련 자원 간의 관계를 명확히 하지 못해 혼란 유발

2. 예시: 잘못된 vs. 올바른 설계

• 잘못된 예: /getUsersWithTasks (동사 사용, 비유연)
• 올바른 예: /users?withTasks=true (쿼리 파라미터, 확장 가능)
• 추가 조건 시: /users?withTasks=true&active=true

3. REST 설계 원칙 준수 방법

• 엔드포인트에 동사 사용 금지 (예: createUser → POST /users)
• 쿼리 파라미터로 조건 추가 (예: /users?role=admin)
• 자원 중심 설계 (예: 사용자, 태스크 등 명사 기반)

4. 장점: 정리된 API의 이점

• 유연성 확보: 필터 조건 추가 시 기존 엔드포인트 변경 필요 없음
• 확장성 향상: 새로운 기능 추가 시 기존 구조에 영향 없음
• 유지보수 용이: 명확한 자원 기반 설계로 오류 감소

결론

• REST API 설계 시 자원 중심으로 설계하고, 쿼리 파라미터를 활용해 조건을 추가하세요.
• 동사 기반 엔드포인트는 절대 사용하지 말고, 기존 REST 원칙을 준수하세요.
• 예: /users?withTasks=true 대신 /getUsersWithTasks 사용 금지.