Discovery dell'API

WebBlocks CMS espone una Content API orientata alla discovery per strumenti di IA e di operatore attendibili. Uno strumento esterno dovrebbe aver bisogno soltanto dell'URL base dell'API del CMS e di un token dell'API del CMS per conoscere gli endpoint disponibili, gli schemi, gli esempi e il flusso di lavoro sicuro dei contenuti.

Per gli strumenti locali di IA o di operatore, memorizzate l'URL base dell'API invece della radice pubblica del sito:

La prima richiesta dovrebbe essere:

GET /webadmin/api è volutamente sicuro per l'uso pubblico. Senza un token Bearer valido restituisce soltanto un JSON di bootstrap minimo:

• nome del prodotto
• versione dell'API
• authenticated: false
• un collegamento a sé stessa
• un breve messaggio che invita il chiamante ad autenticarsi

Non deve restituire l'inventario degli endpoint, i dati del sito, i contratti di contenuto, le anteprime dei token, gli hash dei token, i dettagli degli utenti, i percorsi locali o gli elementi interni del server.

Con un token Bearer valido dell'API del CMS, la discovery restituisce:

• product: WebBlocks CMS
• cms_version e product_version
• api_version
• authenticated: true
• i nomi delle capability del token, senza il valore del token, l'anteprima del token o il suo hash
• i passi successivi consigliati
• i collegamenti per OpenAPI, la guida IA, il contratto di contenuto, gli esempi, validate/apply, le pagine, la pubblicazione delle pagine, la pubblicazione dei blocchi di proprietà della pagina, la navigazione e gli Shared Slot

La risposta autenticata è il contratto di bootstrap canonico per gli strumenti di IA e di operatore. Gli strumenti dovrebbero seguire i collegamenti restituiti invece di presupporre l'accesso al file system locale del repository del CMS o alla documentazione del pacchetto.

Per i piani di contenuto, page.path e expected_path sono percorsi pubblici canonici di Page Translation, come /contact o /docs/internal-content-api. /p/... esiste solo per compatibilità pubblica legacy e non dovrebbe essere generato dai nuovi strumenti.

I collegamenti di discovery attuali includono:

I collegamenti di validate/apply dei contenuti supportano sia la modalità di piano create_draft_page sia replace_existing_draft_page. Utilizzate GET /webadmin/api/content-contract per l'elenco aggiornato delle modalità e per le regole di sicurezza.

I collegamenti di pubblicazione richiedono content.publish. POST /webadmin/api/pages/{page}/publish pubblica per impostazione predefinita soltanto la pagina, con include_page_owned_blocks: false; non pubblica i blocchi in bozza a meno che la richiesta non imposti esplicitamente include_page_owned_blocks: true. La pubblicazione a cascata degli Shared Slot non è supportata e restituisce un riscontro di validazione in JSON. POST /webadmin/api/pages/{page}/publish-page-owned-blocks pubblica i blocchi idonei di proprietà della pagina in stato di bozza o in revisione senza modificare lo stato del flusso di lavoro della pagina.

GET /webadmin/api/examples/contact-page mostra un blocco nativo contact_form. Evita volutamente il Trusted HTML, il markup grezzo dei form e i ripieghi mailto:, così gli strumenti possono creare pagine di contatto in bozza sicure attraverso lo stesso contratto strutturato dei blocchi utilizzato dagli operatori nell'area di amministrazione.

I collegamenti protetti richiedono:

I token dell'API del CMS espongono nella discovery le capability selezionate al momento della creazione del token, così gli strumenti possono conoscere le azioni consentite prima di tentare operazioni di scrittura.

Capability standard per la costruzione delle pagine:

• content.read
• content.validate
• content.apply
• navigation.write
• shared-slots.write

Le capability distruttive o di pubblicazione sono opzioni avanzate separate e non vengono selezionate per impostazione predefinita:

• content.publish
• pages.delete

Le operazioni distruttive devono richiedere una capability corrispondente esplicita e non dovrebbero essere concesse ai normali token per la costruzione delle pagine.

Gli strumenti normali per la costruzione delle pagine non dovrebbero presupporre che la pubblicazione sia disponibile. Se content.publish è assente, gli strumenti dovrebbero fermarsi prima di chiamare gli endpoint di pubblicazione e segnalare che è necessario un token di operatore attendibile con capability di pubblicazione.

Gli endpoint della Content API restituiscono errori in JSON invece di redirect del browser, pagine di login o risposte HTML CSRF. I payload di errore includono collegamenti di orientamento quando pertinenti:

• api_discovery_url
• openapi_url
• documentation_url
• example_url

Comportamento atteso degli stati:

• 401 per token mancanti, non validi o revocati
• 403 per capability mancanti
• 422 per payload di contenuto non validi

Le risposte di discovery, OpenAPI, guida IA, esempi e contratto di contenuto non devono esporre valori reali dei token, hash dei token, valori di .env, percorsi del file system locale, percorsi del server, stack trace, eccezioni grezze, elementi interni del database, elenchi di utenti o dettagli privati dell'operatore.

Gli URL di anteprima come /webadmin/pages/{page}/preview sono rotte del browser o dell'area di amministrazione. Richiedono una sessione browser di amministrazione autenticata e non vengono aperti con i token Bearer dell'API del CMS. Un redirect al login da quell'URL significa che manca la sessione del browser; non è un errore di autenticazione della Internal Content API.