OpenAgenda API

Le OpenAgenda API offrono l'accesso in lettura e scrittura di eventi ed associazioni.

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. Il formato di default della risposta dei moduli content è JSON.

Autenticazione

Alcune richieste richiedono che il client effettui l'autenticazione. Al momento è disponibile l'autenticazione Basic. Le credenziali per utilizzare le risorse protette possono essere create dall'ambiente di amministrazione del sito ospitante: le ACL ivi definite sono valide anche per le richieste via API.

Codici di errore

Errori
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
500 Internal Server Error

Infrastruttura dell'informazione

Le OpenAgenda API espongono un livello REST specializzato del content model di eZ Publish Legacy (vedi https://doc.ez.no/eZ-Publish/Technical-manual/4.x/Concepts-and-basics/Content-management).

Per lavorare con i contenuti di tipo Evento ed Associazione attraverso le API è necessario perciò conoscere l'architettura dell'informazione del sito ospitante (attraverso l'esplorazione delle API di classe) e coniugarla nei contenuti sui cui si intende lavorare. Il formato dei contenuti restituiti dalle API, pur avendo una struttura di base identica, varia a seconda della classe di contenuto che istanzia.

Attributi e datatype

L'elemento minimo del content model di eZ Publish è l'attributo. La classe è infatti la collezione di un determinato numero di attributi di classe (class attributes) e in ciascun contenuto di conseguenza vengono rappresentati gli attributi di oggetto.

Ciascun attributo è caratterizzato da un datatype: la tipologia di contenuto che rappresenza. Ad esempio un attributo con datatype ezstring rappresenta una stringa, uno con datatype ezinteger un numero intero.

La risorsa contenuto 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 utili per la ricerca quali l'identificativo unico della risorsa, la classe di contenuto utilizzata, le date di pubblicazione e di modifica, la sezione e gli stati in cui il contenuto è classificato, l'autore, gli id dei nodi in cui il contenuto è collocato nell'alberatura un numero intero.

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 . 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.