HTTP Content Negotiation을 통한 단일 URL 기반 Human-Agent 듀얼 렌더링 아키텍처

Context

웹 서비스의 독자가 인간과 AI Agent로 이원화됨에 따라 별도의 API 구축 및 유지보수 비용이 증가하는 한계 발생. 기존 방식은 별도의 Route, Auth, Serializer를 구현하여 데이터 동기화 및 관리 포인트가 중복되는 구조적 비효율성을 가짐.

Technical Solution

• Content Type 정의 단일화를 통한 Controller 및 Serializer 작성 단계 제거
• HTTP Accept 헤더를 분석하여 text/html과 text/markdown을 동적으로 결정하는 MediaTypeAcceptNegotiator 로직 구현
• 브라우저 확인을 위한 쿼리 파라미터(?raw, ?format=md) 기반의 명시적 Override 메커니즘 제공
• Vary: Accept 헤더 설정을 통해 동일 URL 내 서로 다른 포맷의 캐시 오염(Cache Contamination) 방지
• Content-type 메타데이터를 기반으로 /robots.txt, /sitemap.xml, /llms.txt 등 Agent용 Discovery Route 자동 생성