API di consegna

Legga da Atlas pagine pubblicate, voci, contenuti globali, percorsi e reindirizzamenti, e segnali la build del Suo sito web.

Questa pagina è stata tradotta dall'inglese. In caso di differenze, fa fede la versione inglese. Leggi in inglese

L’API di consegna è il modo in cui il Suo sito web legge i contenuti pubblicati. La chiami solo da codice server.

URL di base e autenticazione

https://<delivery host>/v1/delivery/environments/{environmentId}
Authorization: PublishedConsumer <delivery token>

Ogni token appartiene a un solo ambiente. Sviluppo e Produzione hanno token separati.
I token sono composti da 43 caratteri casuali, vengono mostrati una sola volta, sono validi da 1 a 365 giorni e possono essere revocati in qualsiasi momento in Studio. Atlas ne archivia soltanto l’impronta.
Un token di Produzione legge solo il rilascio attivo di quell’ambiente.

Cache

Le risposte pubblicate contengono:

Cache-Control: public, max-age=0, s-maxage=60, stale-while-revalidate=300
ETag: W/"…"
X-Atlas-Content-Version: …
Vary: Authorization, Accept-Encoding

Invii If-None-Match con l’ultimo ETag; Atlas risponde 304 Not Modified quando nulla è cambiato. Lo abbini ai webhook per aggiornare alla pubblicazione. Le risposte di anteprima e di distribuzione sono private, no-store.

Endpoint

`GET /site`

L’ambiente, il suo rilascio attivo (Produzione), la versione dei contenuti e il digest e la versione del contratto attivo.

`GET /routes`

Ogni percorso pubblicato, per la Sua sitemap e per la generazione statica: route, pageType, entryId, title, lastModified, noindex, locales. Fino a 5.000 percorsi.

`GET /pages?route=/about&locale=en`

Una pagina pubblicata.

Campo	Contenuto
`page`	`id`, `route`, `title`, `pageType`, `publishedAt`, `entryId`
`document`	`pageType`, `pageFields` e `regions`: ogni regione è un elenco ordinato di sezioni
`document.regions[key][n]`	`id`, `component { id, version }`, `props`, `hidden`
`entry`	La voce associata alla pagina, se il suo tipo di pagina ne ha una
`seo`	`title`, `description`, `noindex`, `structuredDataType`, `canonicalPath`, `faq`
`head`	`title`, `meta[]`, `links[]` e `jsonLd[]` pronti da stampare, oppure `null` con `headProblem`
`assets`	Ogni immagine usata dalla pagina, per id di asset: `url`, `renditions`, `alt`, `focalPoint`
`locale`, `direction`, `translation`, `alternates`	Lingua della risposta, `ltr`/`rtl`, se mancava una traduzione e le altre lingue
`etag`	L’ETag della revisione

404 quando a quel percorso non c’è nulla di pubblicato. Ignori le sezioni in cui hidden è true. Per l’uso di head vedere Ricerca e risposte dell’IA.

`GET /preview/pages?token=…&locale=en`

Una pagina in bozza per un link di anteprima. Solo Sviluppo (404 in Produzione). Non la metta mai in cache. 403 PREVIEW_INVALID per un token errato, 410 PREVIEW_EXPIRED dopo 15 minuti.

`GET /entries?collection=projects`

Le voci di una raccolta.

Parametro	Esempio	Note
`collection`	`projects`	Obbligatorio
`locale`	`ar`
`filter`	`category:water,featured:true`	Coppie `campo:valore`, separate da virgole
`sort`	`-publishedAt`, `title`, `slug`, `featured`, `field.year`	Prefisso `-` per l’ordine decrescente
`fields`	`title,slug,image`	Restituisce solo questi campi
`limit`	`20`	Fino a 100. Lo imposti sempre; senza di esso la risposta può essere grande
`page`	`2`

Restituisce entries, assets e meta.pagination.

`GET /feed?collection=news&limit=20`

Le ultime voci di una raccolta editoriale, per RSS e per gli elenchi di notizie. 404 FEED_NOT_EDITORIAL per le altre raccolte.

`GET /globals?locale=en`

Contenuti condivisi come site-header e site-footer: { globals: { key: { data, revision, publishedAt } }, assets }.

`GET /redirects`

{ redirects: [{ from, to, status }] }. Li applichi nel Suo middleware o nei reindirizzamenti di next.config.

`GET /media/{assetId}?rendition=…`

Reindirizza (302) a un URL firmato dell’immagine valido per 15 minuti. Non serve alcun token, quindi può usarlo in <img src>.

`GET /sitemap.xml`, `GET /robots.txt`, `GET /llms.txt`

File per la radice del Suo sito, costruiti dal rilascio attivo (Produzione) o bloccati (Sviluppo: sitemap vuota, Disallow: /, X-Robots-Tag: noindex, nofollow). Li inoltri dal Suo dominio in modo che il token resti sul Suo server; vedere Ricerca e risposte dell’IA. 409 SITE_ADDRESS_MISSING finché l’ambiente non ha un indirizzo del sito web.

Segnalare una distribuzione

POST /deployments, chiamato dal Suo sito web all’avvio:

{
  "bundleDigest": "<sha256 hex of the contract bundle this build renders>",
  "bundleVersion": "1.4.0",
  "commit": "a1b2c3d",
  "components": [{ "id": "acme.home.hero", "version": "1.0.0" }],
  "runtime": "node",
  "siteOrigin": "https://dev.example.com"
}

Lo state della risposta è in-sync, missing-components, different-contract, unknown-contract o no-contract, con il digest attivo ed eventuali componenti mancanti. runtime è node o cloudflare-workers. Fino a 500 componenti.

Errori

Gli errori sono JSON con un code stabile. Vedere Limiti ed errori.

URL di base e autenticazione

Cache

Endpoint

GET /site

GET /routes

GET /pages?route=/about&locale=en

GET /preview/pages?token=…&locale=en

GET /entries?collection=projects

GET /feed?collection=news&limit=20

GET /globals?locale=en

GET /redirects

GET /media/{assetId}?rendition=…

GET /sitemap.xml, GET /robots.txt, GET /llms.txt