사이트 / CMS API 사용하기
API v1으로 플랫폼 또는 독립 CMS의 인증, 콘텐츠 편집 및 게시를 수행합니다.
사이트 / CMS API 사용하기
API v1은 외부 통합과 사이트·CMS 데이터를 연결합니다. 배포 환경의 계약을 확인하고 권한을 제한한 키를 만든 다음 버전 보호를 적용하여 초안을 저장합니다.
서비스와 배포 선택
QOKIT_API_URL을 API 서비스 출처(로컬은 http://localhost:7777) 또는 독립 설치 출처로 설정합니다. QOKIT_PROJECT_ID는 프로젝트 ID입니다. 내보내기 패키지는 data/seed.json의 project.id에 저장합니다. 공개 읽기는 프로젝트 slug를 사용합니다.
| 배포 | 기능 |
|---|---|
| 플랫폼 | CMS 관리, 내보내기 및 플랫폼 게시 |
cms-managed | 로컬 CMS 관리 및 사이트 렌더링 |
cms-only | 로컬 CMS 관리 및 공개 headless 읽기; 사이트 렌더링 없음 |
site-only | 정적 HTML 페이지와 자산만 제공; 런타임 API 없음 |
계약 확인
각 서비스는 지원하는 작업만 제공합니다. 지원하지 않는 작업은 404를 반환합니다. API 1.0은 기존의 버전 없는 경로와 호환됩니다.
| 경로 | 용도 |
|---|---|
GET /v1/openapi.json | OpenAPI 3.1: 본문, 응답, 권한 및 사전 조건 |
GET /v1/capabilities | API 버전, 배포 유형 및 지원 작업 |
GET /v1/sdk/client.mjs | 의존성이 없는 JavaScript 클라이언트 |
GET /v1/sdk/client.d.mts | 대응하는 TypeScript 선언 |
API 키 만들기
플랫폼 로그인을 완료하고 받은 accessToken을 SESSION_TOKEN으로 사용합니다. 계정에 사이트 설정 관리 권한이 있어야 합니다. 키 발급 전에 필요한 인증을 모두 완료합니다.
curl --fail-with-body "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'독립 CMS에서는 배포 소유자의 이메일과 비밀번호로 로그인하고 세션 Cookie를 저장한 후 키를 만듭니다.
curl --fail-with-body -c cookies.txt "$QOKIT_API_URL/api/auth/login" \
-H 'Content-Type: application/json' \
-d '{"email":"owner@example.com","password":"your-deployment-password"}'
curl --fail-with-body -b cookies.txt "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
-H 'Content-Type: application/json' \
-d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'생성 시에만 token을 반환합니다. 서버 환경 변수 QOKIT_SITE_API_KEY에 저장합니다. 요청은 qk_site_로 시작하는 Bearer 토큰을 사용합니다. 기본 유효 기간은 90일이며 1–365일로 설정할 수 있습니다. 프로젝트당 활성 키는 최대 50개입니다. 설정 관리 권한이 있는 로그인 세션으로 GET /v1/projects/{id}/api-keys에서 목록을 조회하고 DELETE /v1/projects/{id}/api-keys/{keyId}에서 취소합니다.
통합에 필요한 권한만 선택합니다. 요청마다 생성자의 현재 접근 권한과 역할을 확인합니다. 만료, 취소 및 역할 변경은 다음 요청부터 적용됩니다. API 키는 다른 키를 관리할 수 없습니다.
| Scope | 용도 |
|---|---|
content:read / content:write | 컬렉션과 항목 읽기 / 편집 |
content:publish | 명시적 게시 및 항목을 게시하는 쓰기 |
pages:read / pages:write | runtime 읽기 / 페이지 내용, 구조, SEO 및 폼 편집 |
media:read / media:write | 미디어와 폴더 읽기 / 관리 |
settings:read / settings:write | 사이트 설정 읽기 / 편집 |
users:read / users:write | CMS 사용자 읽기 / 관리 |
leads:read / leads:write / analytics:read | 잠재 고객 읽기 / 갱신 및 CMS 대시보드 조회 |
marketing:read / marketing:write | 마케팅 콘텐츠 읽기 / 생성 |
deployments:read / deployments:write | 플랫폼 내보내기 및 게시 작업 |
sync:write / updates:read / updates:write | 독립 설치 동기화 및 서명된 업데이트 |
SDK로 초안 저장
워크스페이스 패키지는 @qokit/site-api이며 아직 npm에 게시되지 않았습니다. 외부 프로젝트에서는 클라이언트 파일 두 개를 sdk에 다운로드합니다. 새 내보내기 패키지는 이미 포함합니다.
mkdir -p sdk
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.mjs" -o sdk/client.mjs
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.d.mts" -o sdk/client.d.mts예제에는 content:read와 content:write가 필요합니다. en을 프로젝트에서 활성화한 언어로 바꿉니다. 새 예제 컬렉션을 만들므로 다시 실행할 때 기존 컬렉션 ID를 사용합니다.
import { createSiteApiClient } from './sdk/client.mjs';
const api = createSiteApiClient({
baseUrl: process.env.QOKIT_API_URL,
projectId: process.env.QOKIT_PROJECT_ID,
token: process.env.QOKIT_SITE_API_KEY
});
const collection = await api.collections.create({
key: 'integration_example', name: 'Integration example', kind: 'generic', fields: []
});
const draft = await api.entries.create(collection._id, {
title: 'Integration draft', locale: 'en', status: 'draft', fields: {}
});
const saved = await api.entries.update(draft._id, { title: 'Reviewed copy' }, {
expectedUpdatedAt: draft.updatedAt
});
console.log(saved._id, saved.updatedAt);초안 저장은 게시된 항목의 이전 공개 스냅샷을 유지합니다. 검토 후 content:publish 권한이 있는 키로 저장된 버전을 명시적으로 게시할 수 있습니다. 플랫폼 페이지 편집은 사이트 게시 절차를 완료할 때까지 초안입니다.
await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });복구하려면 api.entries.revisions(id)를 읽은 후 api.entries.restore(id, revisionId, { expectedUpdatedAt })를 호출합니다. 다른 작업은 api.request(path, options)로 호출하며 idempotencyKey도 지원합니다. 클라이언트는 쓰기를 자동으로 재시도하지 않습니다.
관리 경로
이 경로 앞에 /v1/projects/{id}를 붙입니다. OpenAPI에서 모든 작업, 필드 및 배포별 요건을 확인합니다. DELETE는 컬렉션, 항목 및 미디어를 보관 처리합니다.
| 경로 | 메서드 |
|---|---|
/cms/collections | GET, POST |
/cms/collections/{collectionId} | PUT, DELETE |
/cms/collections/{collectionId}/entries | GET, POST |
/cms/entries/{entryId} | GET, PUT, DELETE |
/cms/entries/{entryId}/publish | POST |
/cms/entries/{entryId}/revisions | GET |
/cms/entries/{entryId}/revisions/{revisionId}/restore | POST |
/cms/media, /cms/media/folders | GET, POST |
/cms/media/{assetId}, /cms/media/folders/{folderId} | PUT, DELETE |
/runtime, /content/{locale} | GET; PUT /content/{locale} |
/site/pages, /site/pages/{pageId}, /site/pages/{pageId}/seo, /site/forms | POST, DELETE, PUT, PUT |
/cms/settings | GET, PUT |
/cms/users, /cms/users/{memberId} | GET / POST, PUT / DELETE |
/leads, /leads/{leadId} | GET, PUT |
플랫폼 미디어는 URL 등록과 업로드 준비를 지원합니다. 독립 업로드는 fileName, contentType, contentBase64를 사용하고 10 MB 제한 및 파일 서명 검사를 적용합니다. 플랫폼 사용자 변경은 Idempotency-Key가 필요하고 로컬 사용자 생성은 12–1024자 비밀번호가 필요합니다. CSV, 일괄 쓰기와 번역 연결은 플랫폼 확장입니다.
버전, 페이지 처리 및 오류
갱신, 보관 및 수정 이력 복구는 expectedUpdatedAt에 마지막으로 읽은 updatedAt을 전달해야 합니다. 버전이 없으면 428, 오래된 버전이면 409를 반환합니다.
구조, SEO 및 폼은 GET /v1/projects/{id}/runtime을 읽고 content.updatedAt과 siteVersion.updatedAt을 각각 baseContentUpdatedAt과 baseSiteVersionUpdatedAt으로 제출합니다. 플랫폼에서는 Builder 수정 이력과 활성 편집 임대도 확인합니다.
목록 기본값은 page=1&pageSize=24이며 페이지당 최대 100개입니다. 관리 목록은 items, 공개 목록은 entries를 반환합니다. 수정 이력과 폴더는 배열입니다. 콘텐츠 내보내기는 모든 페이지를 읽어야 합니다.
{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}응답은 X-Request-Id와 X-Qokit-Api-Version을 포함합니다. 오류에는 고정 코드와 요청 ID가 있습니다.
{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}401은 키 유효성을, 403은 scope와 생성자 접근 권한을 확인합니다. 409는 다시 읽고 변경을 비교하며 428은 버전을 추가합니다. 429는 Retry-After를 따릅니다. 키/주소당 분당 300회이며 플랫폼에는 IP 및 쓰기 제한도 적용됩니다.
독립 설치 설정
플랫폼 브라우저 통합은 CORS_ALLOWED_ORIGINS를 사용합니다. 독립 키의 브라우저 요청은 SITE_API_ALLOWED_ORIGINS에 정확한 출처를 설정합니다. Cookie 관리는 같은 출처를 유지합니다. 공개 CMS 읽기는 CMS_ALLOWED_ORIGINS도 사용할 수 있습니다. CMS-only 미디어 URL은 CMS_PUBLIC_URL을 설정합니다.
비공개 data/api-security.json과 data/api-revisions.json을 포함한 전체 데이터 디렉터리와 업로드를 백업합니다. 비밀번호와 키는 해시로 로컬에 보관됩니다. 각 디렉터리에는 하나의 Node 쓰기 프로세스만 사용합니다.
기존 내보내기 패키지는 서명된 runtime 업데이트로 v1을 얻습니다. 업그레이드 후 HTTP로 현재 계약과 클라이언트를 받습니다. 패키지 파일은 내보내기 시점의 스냅샷입니다.
인증 정보 없는 공개 읽기는 다음을 참고합니다: 공개 콘텐츠 API 호출.
최종 업데이트일