La risoluzione di una pagina e la richiesta principale dell'API. Riceve l'URL richiesto dal visitatore e restituisce la pagina pubblicata corrispondente, completa di route, contenuto risolto, regioni e componenti. Una sola chiamata fornisce tutto il necessario per costruire la pagina.
Endpoint
L'endpoint accetta il metodo POST. L'URL da risolvere viaggia nel corpo della richiesta e non nella query string: la query string del'endpoint non partecipa alla risoluzione.
Il corpo e un oggetto JSON con i campi seguenti. Solo requestedUrl e necessario: gli altri campi alimentano la registrazione statistica della visita e vanno valorizzati soltanto quando il client la richiede.
Campo
Tipo
Descrizione
requestedUrl
stringa
Percorso della pagina richiesta dal visitatore. Viene normalizzato prima della ricerca. Il valore vuoto corrisponde alla home page.
clientId
stringa o null
Identificativo del visitatore generato dal client. Se valorizzato attiva la registrazione statistica della visita.
ipAddress
stringa o null
Indirizzo IP del visitatore, rilevato dal client che espone il sito.
userAgent
stringa o null
User agent del browser del visitatore.
referer
stringa o null
Pagina di provenienza del visitatore.
acceptLanguage
stringa o null
Lingue dichiarate dal browser del visitatore.
queryParameters
elenco di coppie
Parametri della query string originale, come coppie key e value. Non partecipano alla ricerca della route.
Il campo queryParameters e sempre un array: quando non ci sono parametri si invia un array vuoto, non null.
Normalizzazione dell'URL richiesto
Il valore di requestedUrl viene normalizzato prima di cercare la route. Il client puo quindi inviare il percorso cosi come lo riceve dal browser, senza ripulirlo.
Query string e frammento vengono scartati: tutto cio che segue ? o # viene ignorato.
Gli spazi iniziali e finali vengono rimossi.
Le barre iniziali e finali vengono rimosse e sostituite da un unico prefisso /.
Il percorso viene convertito in minuscolo.
Un valore vuoto o composto di soli spazi diventa /, cioe la home page.
I valori /Azienda/, azienda e /azienda?utm_source=news risolvono tutti la stessa route /azienda. La normalizzazione riguarda solo la ricerca: il campo route.path della risposta contiene sempre il percorso canonico registrato nel sito.
Registrazione statistica della visita
Il campo clientId governa la registrazione statistica. Se contiene un valore, la chiamata registra la visita e utilizza anche ipAddress, userAgent, referer, acceptLanguage e queryParameters. Se e vuoto o assente, nessun dato analitico viene raccolto e gli altri campi restano inutilizzati.
La registrazione statistica avviene solo se il client la richiede esplicitamente valorizzando clientId. Spetta al client rispettare i consensi raccolti prima di popolare i campi del visitatore.
Anteprima di una pagina non pubblicata
In condizioni normali l'endpoint restituisce soltanto route pubblicate. Una route non pubblicata diventa raggiungibile inviando in queryParameters la coppia con chiave preview e come valore il token di anteprima generato dal pannello.
Il token viene verificato prima della risoluzione. La chiamata restituisce la pagina solo se il token e valido, se appartiene alla route richiesta e se appartiene al sito indicato negli header. In caso contrario la risposta e 404, come per una pagina inesistente.
{
"requestedUrl": "/azienda",
"clientId": "7f9c1b2e-4a55-4f0e-9a3b-0c1d2e3f4a5b",
"ipAddress": "93.45.12.201",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
"referer": "https://www.google.com/",
"acceptLanguage": "it-IT,it;q=0.9",
"queryParameters": [
{ "key": "utm_source", "value": "newsletter" }
]
}
Tutti gli esiti dell'endpoint adottano l'involucro comune. Il client verifica sempre il campo success e, quando e false, legge error.code.
Stato
error.code
Condizione
200
assente
Pagina risolta. Il campo data contiene la pagina completa.
400
website_id_invalid
L'header WebsiteId manca o non contiene un identificativo valido.
403
website_authorization_required
L'header WebSecretId manca o e vuoto.
404
content_page_not_found
Nessuna route corrisponde all'URL, la route non e pubblicata, il sito non corrisponde al segreto indicato oppure il token di anteprima non e valido.
Il 403 restituito dalla verifica della firma e diverso: arriva dal filtro applicato prima dell'endpoint, ha corpo testuale Forbidden e non adotta l'involucro JSON. Un 403 senza corpo JSON indica quindi un problema di firma, non di header WebSecretId.
Il 404 non distingue tra le sue cause. Questo e voluto: la risposta non rivela l'esistenza di route non pubblicate ne l'appartenenza di una route a un altro sito.
Gestione dei redirect
Quando nessuna route corrisponde all'URL richiesto, il sistema verifica i redirect attivi del sito. Se ne trova uno permanente o temporaneo con destinazione valorizzata, la risposta e 200 con success a true, ma il contenuto e volutamente incompleto: data.route.redirect e l'unica proprieta valorizzata dell'intera pagina.
L'oggetto redirect espone url, la destinazione, e type, che vale Permanent per un redirect 301 o Temporary per un 302.
Il software di rendering deve verificare data.route.redirect prima di leggere qualunque altra parte della risposta ed emettere il proprio reindirizzamento HTTP con lo stato corrispondente. Proseguendo la lettura si otterrebbe una pagina priva di layout, contenuto e regioni.
Un redirect di altro tipo, o con destinazione non valorizzata, produce 404. Se il sito ha attivo il monitoraggio dei redirect, gli URL non risolti vengono registrati nel pannello come errori 404 da correggere.
La risposta positiva contiene un unico oggetto, la pagina risolta, con una struttura fissa e indipendente dal tipo di contenuto. Le pagine seguenti la descrivono per parti: prima il wrapper di ogni risposta di pagina, poi la route con i metadati SEO, il contesto del sito, il contenuto risolto, le regioni con i componenti globali, le aree di contenuto con i componenti editoriali e infine i tipi condivisi e il formato del testo.
