Le OpenData API offrono l’accesso in lettura dei contenuti, l’accesso alla definizione delle classi e l’accesso all’elenco delle sezioni e degli stati dei contenuti.
Accesso alle API¶
E” possibile accedere alle API attraverso una richiesta HTTP al server API. Il server restituirà la risorsa richiesta con uno status code HTTP coerente con il risultato della richiesta fatta.
Formato della risposta¶
Il formato di default della risposta dei moduli content è JSON. Il formato di default della risposta dei moduli geo è geoJSON.
Autenticazione¶
Alcune richieste richiedono che il client effettui l’autenticazione. Al momento è disponibile l’autenticazione Basic, è in roadmap l’implementazione del formato Oauth/Oauth2.
Lettura di un contenuto¶
GET content/read/$ContentIdentifier
La risposta in JSON è un oggetto Content
La varibile obbligatoria $ContentIdentifier rappresenta un identificatore unico del contentuto, espresso con metadata.id oppure metadata.remoteId
Ricerca di un contenuto¶
GET content/search/$Query
La risposta in JSON è un oggetto SearchResults
La varibile obbligatoria $Query rappresenta la stringa di ricerca. Il server API riconosce un meta-linguaggio per filtrare i contenuti.
Lettura di un punto geografico¶
GET geo/read/$ContentIdentifier
La risposta in geoJSON è un oggetto Feature
La varibile obbligatoria $ContentIdentifier rappresenta un identificatore unico del contentuto.
Ricerca di punti geografici¶
GET geo/search/$Query
La risposta in geoJSON è un oggetto FeatureCollection
La varibile obbligatoria $Query rappresenta la stringa di ricerca. Il server API riconosce un meta-linguaggio per filtrare i contenuti.
Rappresentazione delle risorse¶
Content¶
Esempio di content in formato json
La risorsa contenuto rappresenta il cuore delle API. Essa viene esposta come un oggetto composto da due proprietà che ne rappresentano i metadati e i dati veri e propri.
| Identificatore | Tipo di dato | Descrizione |
| metadata | object | Rappresentazione dei metadati del contenuto |
| data | object | Rappresentazione dei dati del contenuto |
Metadata¶
I metadati sono informazioni non riferibili al contentuto vero e proprio dell’oggetto ma al suo contesto. Attraverso i metadati è possibile raggiungere informazioni utiliu per la ricerca quali l’identificativo unico della risorsa, la classe di contenuto utilizzata, le date di pubblicazione e di modifica…
| Identificatore | Tipo di dato | Descrizione | Note |
| id | integer | Id univoco del contenuto nel server API | Sola lettura |
| remoteId | string | Id univoco del contenuto nel server API impostato dal redattore o dal processo di importazione automatica: per design la sua lunghezza non può superare i 100 caratteri | |
| classIdentifier | string | Identificatore della classe di contenuto utilizzata dalla risorsa esposta | |
| class | uri | Url di accesso alla risorsa classe utilizzata dalla risorsa esposta | Sola lettura |
| sectionIdentifier | string | Identificatore della sezione utilizzata dalla risorsa esposta | |
| stateIdentifiers | array | Array degli identificatori di stato (nel formato <stategroup_identifier>.<state_identifier> utilizzati dalla risorsa esposta | |
| published | Date ISO 8601 | Data di pubblicazione del contenuto | Sola lettura |
| modified | Date ISO 8601 | Data di ultima modifica del contenuto | Sola lettura |
| languages | array | Array degli identificatori di lingua delle traduzioni disponibili della risorsa esposta | Sola lettura |
| name | hash | Array associativo del nome della risorsa per ciascuna traduzione disponibile | Sola lettura |
| parentNodes | array | Array dei Id dei Nodi in cui è collocato l’oggetto informativo | |
| link | uri | Url di accesso alla risorsa richiesta | Sola lettura |
Data¶
| Identificatore | Tipo di dato | Descrizione |
| (Identificatore di lingua) | object | Rappresentazione degli attributi del contenuto |
La risorsa Data espone il contenuto informativo del Content per ciascuna traduzione disponibile. Ad ogni identificatore di lingua corrisponde da un oggetto chiave-valore dove ciascuna chiave è l’identificatore dell’attributo e ciascun valore è rappresentato da un tipo di dato primitivo o strutturato. Data la natura flessibile del content model di eZPublish è necessario ricavare la struttura della risorsa Data attravero la definizione della classe raggiungibile dall’url esposto in content.metadata.class .
SearchResults¶
| Identificatore | Tipo di dato | Descrizione |
| query | string | Stringa di ricerca |
| nextPageQuery | string oppure null | Stringa per ricevere la pagina successiva dei risultati |
| totalCount | integer | Numero totale di contenuti ottenuti dalla ricerca |
| searchHits | Array di Content oppure FeatureCollection | Risultati della ricerca |
La query di ricerca¶
Per eseguire una query occorre specificare una stringa di ricerca Query.
La Query viene effettuata attraverso i filtri e i parametri.
Filtri¶
I filtri sono composti dai un identificatore, un operatore e un valore.
Ad esempio:
titolo = 'Mercatino di Natale'
In questo esempio, il campo è «titolo», l’operatore è «=» e il valore è «“Mercatino di Natale”». Si sta chiedendo al motore di ricerca di restituire tutti i contenuti che hanno un attributo il cui è identificatore «titolo» contiene il valore “Mercatino di Natale”.
Operatori per i filtri¶
| Operatore | Tipo di valore atteso | Esempio |
| = | Stringa compresa tra apici | titolo = “Nel mezzo del cammin” |
| != | Stringa compresa tra apici | titolo != “Nel mezzo del cammin” |
| in e la sua negazione != | Array di stringhe | titolo in [“Nel mezzo del cammin di nostra vita”,”La gloria di colui che tutto move”] |
| contains e la sua negazione !contains | Array di stringhe | titolo contains [“Nel mezzo del cammin di nostra vita”,”La gloria di colui che tutto move”] |
| range e la sua negazione !range | Array di 2 stringhe | from_time range [2014-01-01,2014-12-31] |
L’operatore «contains» produce in AND logico: tutti i titoli che contengono le stringhe “Nel mezzo del cammin di nostra vita” e “La gloria di colui che tutto move” contemporaneamente.
L’operatore «in» produce in OR logico: tutti i titoli che contengono la stringa “Nel mezzo del cammin di nostra vita” oppure la stringa “La gloria di colui che tutto move”.
Parametri¶
| Operatore | Tipo di valore atteso | Esempio | Utilizzo |
| sort | Hash | sort [published => desc] | Ordinamento |
| limit | intero | limit 10 | Numero di risultati per pagina (massimo 100, default 30) |
| offset | intero | offset 10 | Offset per la paginazione |
| classes | stringa o Array di stringhe | classes “event” oppure classes [“event”,”article”] | restrizione sui tipi di contenuto |
| subtree | Array di interi | subtree [2,43,54] | restrizione di sotto albero |
I parametri servono a modificare l’ambito di ricerca e sono rappresentati da una chiave e da un valore.
classes 'event'
In questo esempio la chiave è «classes» e il valore «’event”». Si sta chiedendo al motore di ricerca di restituire tutti contenuti di classe «event».
Ecco un esempio che usa filtri e parametri:
titolo = 'Mercatino di Natale' classes 'event'
E” possibile eseguire ricerche più complesse. Ad esempio per ricerca gli eventi della settimana prossima:
from_time range [today,next week] or to_time range [today,next week] or ( from_time range [*,today] and to_time range [next week,*] ) classes event sort [published => desc]
Il server API mette a disposizione di default una console raggiungibile da (www.domain.tdl/opendata/console)