자체 프론트엔드를 구축할 때 모든 공개 콘텐츠는 사이트 URL https://{your-site}/api/v1/* (또는 영구 시스템 URL https://s-xxx.kanorio.com/api/v1/*)에서 키 없이 직접 가져올 수 있습니다.
전체 엔드포인트 및 매개변수 사양(SSOT): 모든 쿼리 매개변수, 필드 유형, 필터 연산자 및 JSON 응답 예시는 Content Delivery API 참조 페이지의 OpenAPI 사양에서 실시간으로 생성됩니다. 이 가이드는 프론트엔드 통합을 위한 아키텍처 결정 및 일반적인 패턴에 중점을 둡니다.
expand)을 사용하여 사용자 지정 컬렉션을 쿼리하고, 블러 플레이스홀더(placeholder)가 포함된 assets 이미지를 파싱하기.formats), 구조화된 세그먼트(segments) 및 자동 생성된 목차(toc)가 포함된 블로그 게시물 읽기./api/v1/search).npx @kanorio/cli types).외부 프론트엔드에서 Kanorio 대시보드에 구성된 내비게이션 메뉴, 푸터 링크 또는 페이지 SEO 설정을 사용해야 하는 경우, 공유 레이아웃에서 이를 가져올 수 있습니다:
GET /api/v1/site): 사이트 이름, 기본 언어, 시간대, 통화 및 현재 공개 콘텐츠 버전 publicVersion을 가져옵니다.GET /api/v1/globals/headers/primary, GET /api/v1/globals/footer): 내비게이션 트리, CTA 버튼, 소셜 링크 및 로고(최상위 assets 미디어 맵 포함)를 가져옵니다.GET /api/v1/pages, GET /api/v1/pages/{slug}): 페이지 계층 구조, 이동 경로, SEO 필드(title, description, ogImage, canonicalUrl, noindex) 및 페이지 모듈 데이터를 가져옵니다. 홈페이지를 가져오려면 /api/v1/pages/home을 호출하세요.GET /api/v1/redirects): 대시보드에 구성된 리다이렉트와 페이지 이름 변경 시 자동으로 생성된 301 리다이렉트 목록을 가져옵니다. 이를 Next.js 미들웨어 또는 엣지 라우트에 추가하여 SEO를 유지하세요./api/v1/collections/{key}/items)에서 생성한 사용자 지정 컬렉션(예: teachers, courses)을 사용하든, 시스템 동기화된 블로그 컬렉션(blog, blog_categories, blog_tags, blog_authors)을 사용하든 쿼리 구문은 동일합니다:
const res = await fetch( "https://s-k4m9x2p7q8w3.kanorio.com/api/v1/collections/courses/items?filter[level]=beginner&sort=-publishedAt&expand=teacher&limit=20" ); const { items, nextCursor, assets } = await res.json();
expand를 사용하여 참조 해결하기:
컬렉션에 reference 또는 multi_reference 필드(예: 코스의 teacher, 블로그의 authors,categories,tags)가 있는 경우, ?expand=teacher를 추가하면 각 항목에 item.expanded.teacher(전체 fieldData 포함)가 첨부됩니다. 확장된 항목의 이미지도 최상위 assets 맵에 포함되므로 두 번째 요청이 필요하지 않습니다.has_slug / eq_slug 사용하기:
카테고리 페이지(예: /blog/category/recipes)를 구축할 때 먼저 카테고리 ID를 가져올 필요가 없습니다. ?filter[categories][has_slug]=recipes라고 작성하기만 하면(단일 선택 참조에는 eq_slug 사용), 서버가 단일 쿼리에서 일치 항목을 수행합니다.assets[id].placeholder를 이미지 컴포넌트에 전달하기:
최상위 assets 맵에는 모든 비트맵에 대한 url, width, height, alt 및 placeholder(16px WebP Base64 데이터 URL)가 포함되어 있습니다. Next.js의 <Image placeholder="blur" blurDataURL={asset.placeholder} />에서 직접 사용하면 추가 요청 없이 부드럽고 점진적인 로딩이 가능합니다.fields를 사용하여 페이로드 크기 줄이기:
전체 콘텐츠가 필요 없는 목록 페이지의 경우, ?fields=title,excerpt,cover_image,published_at를 추가하여 서버가 지정된 필드만 반환하도록 합니다./api/v1/collections/blog/items를 쿼리하거나 /api/v1/collections/blog/items/{slug}를 통해 단일 항목을 쿼리할 때 ?formats=를 통해 콘텐츠 형식을 제어할 수 있습니다:
formats 없음): fieldData.content는 깔끔한 Markdown을 반환하며, 항목은 최상위 수준에서 구조화된 segments 배열과 toc 배열(H2/H3 id, text, level)을 제공합니다.?formats=html,plaintext(또는 markdown,html,plaintext)를 추가하면 fieldData에 contentHtml 및 contentPlaintext가 포함됩니다.segments 배열은 기사를 { type: "markdown", markdown } 객체와 { type: "cta", presetId, title, description, buttonText, buttonUrl } 객체로 분할하므로, 자체 React/Astro 컴포넌트를 사용하여 프로모션 카드를 렌더링할 수 있습니다./api/v1/search)프론트엔드에 사이트 전체 검색 상자를 추가하려면 브라우저나 서버에서 직접 호출하세요:
const res = await fetch( `https://s-k4m9x2p7q8w3.kanorio.com/api/v1/search?q=${encodeURIComponent(keyword)}&kind=post,page,product&limit=10` ); const { results } = await res.json();
kind는 page, post, product 또는 category(쉼표로 구분)별로 필터링합니다.title, snippet, url 및 유형이 포함되어 있어 실시간 드롭다운 검색 메뉴나 Command-K 검색 패널에 적합합니다.kanorio types)컬렉션 필드에 대한 TypeScript interface 정의를 수동으로 작성할 필요가 없습니다. 프로젝트 루트에서 다음을 실행하세요:
npx @kanorio/cli types --site https://s-k4m9x2p7q8w3.kanorio.com --out src/kanorio.d.ts
CLI는 공개된 /api/v1/collections의 자체 설명 구조(segments, toc, counts와 같은 가상 필드 포함)를 읽어 완전한 FieldData, Expanded, Item 유형과 /pages, /globals, /site에 대한 정의를 생성합니다. 또한 collections.schema.changed 을 구독하여 필드가 변경될 때 유형을 자동으로 업데이트할 수도 있습니다.
OpenAPI에서 생성된 Content Delivery API 참조 페이지를 참조하세요. 각 엔드포인트에는 전체 매개변수 표와 클릭 한 번으로 실행 가능한 curl 명령이 포함되어 있습니다.