Skip to Content
개발자 문서

사이트 / 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.jsonOpenAPI 3.1: 본문, 응답, 권한 및 사전 조건
GET /v1/capabilitiesAPI 버전, 배포 유형 및 지원 작업
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:writeruntime 읽기 / 페이지 내용, 구조, SEO 및 폼 편집
media:read / media:write미디어와 폴더 읽기 / 관리
settings:read / settings:write사이트 설정 읽기 / 편집
users:read / users:writeCMS 사용자 읽기 / 관리
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/collectionsGET, POST
/cms/collections/{collectionId}PUT, DELETE
/cms/collections/{collectionId}/entriesGET, POST
/cms/entries/{entryId}GET, PUT, DELETE
/cms/entries/{entryId}/publishPOST
/cms/entries/{entryId}/revisionsGET
/cms/entries/{entryId}/revisions/{revisionId}/restorePOST
/cms/media, /cms/media/foldersGET, 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/formsPOST, DELETE, PUT, PUT
/cms/settingsGET, 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 호출.

이 가이드가 도움이 되었나요?

최종 업데이트일

페이지 내 목차