공개 콘텐츠 API 호출
API v1으로 게시된 콘텐츠를 읽고 페이지 처리, 언어 대체 및 headless 배포를 다룹니다.
공개 콘텐츠 API 호출
외부 프런트엔드나 콘텐츠 소비 시스템에는 공개 API를 사용합니다. 게시된 항목에는 API 키가 필요 없습니다. 초안과 보관 항목은 숨겨지며 이후 편집도 게시 전까지 비공개입니다.
식별자와 엔드포인트 선택
QOKIT_API_URL은 API 또는 설치 출처, QOKIT_PROJECT_SLUG는 프로젝트 slug, QOKIT_COLLECTION_KEY는 컬렉션 키로 설정합니다. 이 경로는 slug와 키를, 관리 경로는 리소스 ID를 사용합니다.
GET /v1/projects/slug/{slug}/cms/collections/{collectionKey}/entries?locale=en&page=1&pageSize=24
GET /v1/projects/slug/{slug}/cms/collections/{collectionKey}/entries/{entrySlug}?locale=en
GET /v1/projects/slug/{slug}/runtime?locale=en모든 페이지와 항목 상세 읽기
클라이언트 다운로드는 다음 설정을 따릅니다: 사이트 / CMS API 사용하기.
import { createSiteApiClient } from './sdk/client.mjs';
const api = createSiteApiClient({ baseUrl: process.env.QOKIT_API_URL });
const projectSlug = process.env.QOKIT_PROJECT_SLUG;
const collectionKey = process.env.QOKIT_COLLECTION_KEY;
const entries = [];
let page = 1;
let result;
do {
result = await api.publicEntries(projectSlug, collectionKey, {
locale: 'en', page, pageSize: 24
});
entries.push(...result.entries);
page++;
} while (page <= result.totalPages);
if (entries.length) {
const detail = await api.publicEntry(projectSlug, collectionKey, entries[0].slug, {
locale: result.locale
});
console.log(detail.entry.title);
}
console.log(entries.length, result.locale, result.localeFallback);응답 이해
목록은 entries, page, pageSize, total, totalPages를 반환하고 상세는 entry를 반환합니다. 기본 24개, 최대 100개입니다. 첫 페이지만 읽으면 전체 컬렉션을 받지 못합니다.
항목 링크에는 반환된 locale을 사용합니다. localeFallback에는 requestedLocale, resolvedLocale, usedFallback이 있습니다. 지역 언어, 기본 언어, 프로젝트 기본값, 영어 순으로 대체합니다. 최상위 requestedLocale은 배포에 따라 다릅니다.
search, category, brand, minPrice, maxPrice, featured, sort는 호스트 계약을 확인합니다. 적용 여부는 컬렉션에 따라 다릅니다. 검증된 fieldQuery는 플랫폼 확장이며 독립 설치는 400으로 거부합니다.
배포, 출처 및 호환성
플랫폼 공개 runtime은 게시된 사이트 버전을 읽습니다. CMS-managed와 CMS-only는 최신 공개 CMS 읽기를 지원합니다. site-only는 정적 HTML과 자산만 포함하며 콘텐츠 API는 없습니다. CMS-only에는 사이트 렌더러가 없습니다. 관리 키를 프런트엔드 코드에 넣지 마세요.
플랫폼 /projects/slug/{slug} 경로는 유지됩니다. 독립 /api/content/collections/{collectionKey}/entries 경로도 유지되며 페이지 정보는 pagination 안에 있습니다. 새 통합은 v1과 OpenAPI 계약을 사용합니다.
게시된 콘텐츠가 없으면 404, 잘못된 필터는 400을 처리합니다. 429는 Retry-After를 따릅니다. 관리 가이드에 따라 허용할 프런트엔드 출처를 설정합니다.
인증, CORS, 쓰기 및 배포 차이는 다음을 참고합니다: 사이트 / CMS API 사용하기.
최종 업데이트일