Questo è il documento di riferimento per le Application Programming Interface (API) del servizio IRIS GateWay REST.
Queste API sono progettate per essere utilizzate dagli sviluppatori per recuperare le informazioni IRIS e utilizzarle in altre applicazioni.
Al momento queste API coprono estesamente le risorse dai moduli IRIS RM e IRIS AP.
C'è un'ulteriore API per il recupero delle pubblicazioni (IRIS IR). Si tratta di un'API temporanea sviluppata in attesa della prossima versione di IRIS IR che avrà DSpace6 come core e che è previsto per la fine del 2019.
Le API GW REST sono accessibili tramite un browser Web, ma si consiglia l'uso di un client specifico o di plug-in del browser (ci sono diversi plugin per Mozilla Firefox, Google Chrome, ...)
Se si tratta della prima lettura, si consiglia di consultare il documento, altrimenti è possibile passare ai dettagli del servizio REST.
Per accedere all'API GEST REST deve essere utilizzata l'autenticazione di base HTTP su https.
Un account specifico è necessario e può essere fornito dallo staff di IRIS, su richiesta.
Le API GW REST forniscono accesso alle risorse (entità dati) tramite i percorsi URI in base alle convenzioni REST e agli standard RFC HTTP.
Tutte le risposte sono in formato JSON e dalla versione v1 sono permesse solo richieste GET.
Gli URI dell'API REST di GW seguono questo schema:
http://<iris-host>/gw/rest/api/<resource-collection-name>[;full][/<resource-identifier>]
Tutti i nomi delle risorse disponibili resource-collection-name sono dettagliati nelle seguenti sezioni.
Per ottenere l'elenco di tutte le risorse in una raccolta, l'URL costruito deve seguire questo modello
http://<iris-host>/gw/rest/api/<resource-collection-name>
L'elenco può essere filtrato utilizzando i parametri di query come spiegato in questa sezione
Per ottenere una risorsa single resource l'URL costruito deve seguire questo modello
http://<iris-host>/gw/rest/api/<resource-collection-name>/<resource-identifier>
Ad esempio, per recuperare un dipartimento specifico (dipartimento identificato da 328235 per esempio), si dovrebbe accedere a:
https://iris.unixx.it/gw/rest/api/departments/328235
Quasi tutte le raccolte di risorse disponibili sono fornite in due varianti:
Secondo le convenzioni REST:
• viene restituito un array JSON ([]) che richiama un URL che fa riferimento a tutte le risorse in una raccolta
• viene restituito un oggetto JSON ({}) che richiama un URL che fa riferimento a una singola risorsa.
Le richieste GW REST possono specificare vari parametri di filtro che variano da raccolta a raccolta.
I parametri di query standard sono consentiti per le richieste di raccolte o di singole risorse.
Per esempio:
• https://iris.unixx.it/gw/rest/api/public-engagements?validation.relation=mostValidated
• https://iris.unixx.it/gw/rest/api/public-engagements/12345?validation.relation=mostValidated
Tutti i parametri di filtro disponibili per ogni tipo di risorsa sono elencati nella sezione specifica per ogni raccolta.
Le convenzioni REST non specificano come costruire un URL per ottenere una risorsa specifica quando questa risorsa ha più identificatori.
Per soddisfare questo requisito, le API GW REST consentono di specificare quale identificatore si desidera utilizzare quando si effettua una richiesta.
Ad esempio per ottenere una singola persona è possibile utilizzare uno dei seguenti URL:
• https://iris.unixx.it/gw/rest/api/people/12345
• https://iris.unixx.it/gw/rest/api/people/id=12345 (stesso risultato di quello precedente)
• https://iris.unixx.it/gw/rest/api/people/pid=rp12345
• https://iris.unixx.it/gw/rest/api/people/idAb=67890
• https://iris.unixx.it/gw/rest/api/people/cf=XXXXXX00X00X000X
• https://iris.unixx.it/gw/rest/api/people/sourceId=xxxx
• https://iris.unixx.it/gw/rest/api/people/orcid=yyyyyy
Ciascuna delle precedenti richieste restituisce un singolo oggetto JSON {}.
Lo stesso risultato può essere ottenuto facendo queste richieste:
• https://iris.unixx.it/gw/rest/api/people?id=12345
• https://iris.unixx.it/gw/rest/api/people?pid=rp12345
• https://iris.unixx.it/gw/rest/api/people?idAb=67890
• https://iris.unixx.it/gw/rest/api/people?cf=XXXXXX00X00X000X
• https://iris.unixx.it/gw/rest/api/people?sourceId=xxxx
• https://iris.unixx.it/gw/rest/api/people?orcid=yyyyyy
Ciascuna delle precedenti richieste restituisce un array JSON contenente l'oggetto corrispondente [{}].
Tutti gli identificatori disponibili per ogni tipo di risorsa sono elencati nella sezione specifica per ogni raccolta.
Se non viene fornito alcun tipo di identificatore, l'uso dell'identificatore "id" è implicito.
Ogni volta che viene effettuata una richiesta, il payload della risposta conterrà solo le informazioni relative alla risorsa.
Altre informazioni quali errori, impaginazione, ordinamento sono disponibili nelle intestazioni HTTP.
Queste intestazioni sono:
Per la navigazione e l'ordinamento dei risultati, è possibile utilizzare questi parametri di richiesta della query:
Per esempio:
• https://iris.unixx.it/gw/rest/api/people?page=2
• https://iris.unixx.it/gw/rest/api/people?name=xxx&sort=name,id
I campi utilizzabili per l'ordinamento sono:
I filtri di ordinamento utilizzabili effettivi per un tipo di risorsa specifico sono specificati nei dettagli del servizio REST.
Ogni volta che viene effettuata una richiesta, può essere restituito uno dei seguenti HTTP Response Header:
Se è capitato un errore interno (Internal Server Error), è possibile usare queste intestazioni per approfondire il problema:
Nei rilasci futuri, queste intestazioni potrebbero essere rinominate diventando rispettivamente Error-Code e Error-Message.