Skip to Content
Documentazione per sviluppatori

Chiamare l’API pubblica dei contenuti

Leggi contenuti pubblicati con API v1, paginazione, fallback linguistico e distribuzione headless.

Chiamare l’API pubblica dei contenuti

Usa l’API pubblica per frontend esterni o consumatori di contenuti. Le voci pubblicate non richiedono chiavi API. Bozze e archivi sono nascosti; le modifiche successive restano private fino alla pubblicazione.

Scegliere identificatori ed endpoint

Imposta QOKIT_API_URL sull’origine API o installazione, QOKIT_PROJECT_SLUG sullo slug del progetto e QOKIT_COLLECTION_KEY sulla chiave della raccolta. Queste rotte usano slug e chiavi; la gestione usa 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

Leggere tutte le pagine e una voce

Scarica il client seguendo la configurazione in Usare l’API di siti / CMS.

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);

Interpretare la risposta

Le liste restituiscono entries, page, pageSize, total e totalPages; i dettagli restituiscono entry. La dimensione predefinita è 24, massima 100. La prima pagina non comprende tutta la raccolta.

Usa il locale restituito per i collegamenti. localeFallback contiene requestedLocale, resolvedLocale e usedFallback. La sequenza è lingua regionale, base, predefinita del progetto e inglese. Il campo superiore requestedLocale dipende dalla distribuzione.

Consulta il contratto per search, category, brand, minPrice, maxPrice, featured e sort; l’applicazione dipende dalla raccolta. fieldQuery validato è un’estensione della piattaforma; le installazioni indipendenti lo rifiutano con 400.

Distribuzione, origini e compatibilità

Il runtime pubblico della piattaforma legge la versione pubblicata del sito. CMS-managed e CMS-only offrono contenuti pubblici attuali. Site-only contiene solo HTML e risorse statiche, senza API dei contenuti. CMS-only non ha un renderer del sito. Non inserire chiavi di gestione nel frontend.

Restano disponibili le rotte piattaforma /projects/slug/{slug} e quelle indipendenti /api/content/collections/{collectionKey}/entries, con metadati annidati in pagination. Le nuove integrazioni usano v1 e il relativo contratto OpenAPI.

Gestisci 404 per contenuti pubblicati assenti e 400 per filtri non validi. Per 429, rispetta Retry-After. Configura le origini frontend consentite secondo la guida di gestione.

Per autenticazione, CORS, scritture e differenze di distribuzione, consulta Usare l’API di siti / CMS.

Questa guida è stata utile?

Ultimo aggiornamento il

In questa pagina