실용적인 RESTful API 설계 모범 사례 (Vinay Sahni)
Source
Evernote/Technote scraps/Best Practices for Designing a Pragmatic RESTful API Vinay Sahni.md
Summary
이 문서는 웹 애플리케이션용 공개 API 설계 시 고려해야 할 실용적인 모범 사례를 제시합니다. 저자는 SupportFu API 설계 경험을 바탕으로, 학술적인 표준 준수보다 개발자 경험(DX)과 실용성을 우선시하는 접근법을 제안합니다. 주요 원칙으로는 RESTful URL 및 HTTP 메서드 사용, SSL 필수 적용, URL 기반 버전 관리, JSON 선호, Link 헤더 기반 페이지네이션, 토큰 기반 인증, 명확한 에러 처리 및 HTTP 상태 코드 활용 등을 포함합니다. 또한 HATEOAS는 현재로서는 비실용적이며, 응답 엔벨로프는 기본으로 사용하지 않는 것이 좋다고 조언합니다.
Key Points
- API는 개발자를 위한 UI이므로 탐색성과 사용 편의성을 최우선으로 고려해야 함
- RESTful 원칙 준수: 리소스는 명사로 표현, HTTP 메서드(GET, POST, PUT, PATCH, DELETE)의 의미를 명확히 활용
- 보안: 모든 통신에 SSL 적용
- 버전 관리: 헤더가 아닌 URL 경로(예: /v1/)를 통해 버전 관리
- 데이터 형식: JSON을 기본으로 사용, XML은 필요시만 사용. JSON 필드명은 camelCase 권장(단, snake_case 가독성도 고려)
- 응답 최적화: 필드 제한 기능 제공, 기본값으로 pretty print 지원 및 gzip 압축 지원, 응답 엔벨로프 사용 지양
- 페이지네이션: Link 헤더를 사용하여 이전/다음 페이지 정보 제공
- 인증: 토큰 기반 인증 사용, 위임이 필요할 경우 OAuth2 활용
- 에러 처리: 소비 가능한 에러 페이로드 정의 및 HTTP 상태 코드 효과적 사용
- HATEOAS: 현재 기술 환경에서는 실용성이 낮아 권장하지 않음
- 문서화: API의 품질은 문서화의 질에 달려 있으므로 훌륭한 문서 제공 필수