Introduzione

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.

Autenticazione e autorizzazione

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.

Convenzioni sugli URI REST

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:

• base (predefinito)

1. Viene restituito solo un piccolo sottoinsieme di dati.
2. I risultati sono divisi in pagine e ogni pagina mostra 20 risultati.
3. Il numero di elementi per pagina può essere personalizzato fino a 500 ma non è consigliabile, per evitare problemi di prestazioni.
4. Per modificare la divisione delle pagine, deve essere utilizzato il parametro pageSize. 
5. DEVE essere utilizzato per la ricerca.

• completo (identificato dal parametro ;full)

1. Tutti i metadati vengono restituiti.
2. DEVE essere utilizzato per recuperare informazioni dettagliate per un articolo specifico.
3. Questa versione NON fornisce tutte le funzionalità di filtraggio fornite dalla controparte di base.
4. Se questa versione viene utilizzata per effettuare una ricerca, la dimensione della pagina è limitata a un articolo per pagina per evitare problemi di prestazioni, poiché il singolo elemento può contenere molte informazioni
5. Nel prossimo futuro saranno presumibilmente realizzati dei miglioramenti per consentire l'aumento del numero di articoli per pagina in questa versione completa, al fine di ottimizzare l'accesso batch.

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.

Parametri di filtro per le richieste REST

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.

Convenzioni sulle risposte REST

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:

• Item-Count
  numero di oggetti trovati
• Item-Per-Page
  numero di elementi per pagina
• Page
  numero della pagina corrente
• Page-Count
  numero di pagine disponibili
• Rest-Version
  versione del rest service
• Sort
  lista dei campi di ordinamento in formato csv 
• Dir
  direzione di ordinamento (asc|desc)

Risultati di ricerca e ordinamento REST

Per la navigazione e l'ordinamento dei risultati, è possibile utilizzare questi parametri di richiesta della query:

• page
  numero di pagina da recuperare
• sort
  campo di ordinamento
• dir
  direzione dell'ordinamento (asc, desc)

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:

• id
• pid
• year
• name
• startDate
• lastModified

I filtri di ordinamento utilizzabili effettivi per un tipo di risorsa specifico sono specificati nei dettagli del servizio REST.

Gestione degli errori REST

Ogni volta che viene effettuata una richiesta, può essere restituito uno dei seguenti HTTP Response Header:

• 200: OK
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 500: Internal Server Error

Se è capitato un errore interno (Internal Server Error), è possibile usare queste intestazioni per approfondire il problema:

• error-code
  codice di errore
• error-message
  messaggio dei dettagli dell'errore.

Nei rilasci futuri, queste intestazioni potrebbero essere rinominate diventando rispettivamente Error-Code e Error-Message.

Controllo di versione delle risorse REST

In IRIS ci sono alcune risorse abilitate per effettuare il versioning (versionamento).

Si consideri questo caso d'uso che chiarisce lo scenario.

Un ricercatore crea un oggetto (gruppo di lavoro, laboratorio, terza missione, ...) e aggiunge alcune informazioni: questo elemento è noto come master item.

Ad un certo punto, si decide di contrassegnare questo elemento come "approvato": questo è il momento in cui viene generata una "istantanea" (snapshot) per congelare le informazioni.

Quindi ora abbiamo due versioni dello stesso articolo: l'oggetto master (approvato) e quello snapshot (approvato).

Ammettiamo che alcuni giorni dopo l'utente scopra un errore di battitura e riapra quell'oggetto, o più precisamente riapra l'oggetto principale, perché l'istantanea è congelata.

Abbiamo ancora due versioni dello stesso oggetto: la master riaperta e la snapshot approvata.

Ora si decide di contrassegnare nuovamente questo elemento come "approvato": in questo preciso momento viene creata una nuova snapshot.

Ora abbiamo tre versioni dello stesso item: master (approvato) e due immagini snapshot (approvato).

Ogni ciclo di riapertura / approvazione genera una nuova istantanea.

I servizi REST espongono solo l'elemento principale e l'ultima istantanea, se disponibile.

Per semplificare la ricerca vengono introdotti due nuovi concetti:

most updated item → articolo più aggiornato: questo è sempre l'oggetto master

most validated item → articolo più validato: questo può essere il master item o l'ultima snapshot. Se l'elemento si trova in uno stato precedente allo stato di approvazione (o non è abilitato il controllo di versione), allora è disponibile solo l'elemento principale master. Per convenzione, esso sarà il most validated item, anche se non è mai stato approvato.

D'altra parte, se l'elemento si trova in uno stato dopo lo stato di approvazione, sono disponibili sia gli elementi master che gli snapshot. In questo caso l'elemento snapshot è quello "più validato".

Non tutte le risorse sono soggette al controllo di versione, ma quando lo sono è possibile utilizzare questo parametro di filtro aggiuntivo:

validation.relation 

Gli unici valori consentiti sono:

• master
• mostValidated
• all

Se il parametro validation.relation non viene fornito, allora si assume che esso coincida col most validated.

NB: Si ricordi che gli ID vengono generati per ogni snapshot e master.

Gli oggetti visibili in IRIS RM o IRIS AP sono identificati dall'id master.

Gli ID delle snapshot sono disponibili nella scheda "Versioni".

Controllo di versione degli Endpoint REST

Ogni endpoint di raccolta può essere versionato.
La versione corrente è v1.
Se non diversamente specificato, si assume che sia la versione v1.
Per utilizzare una versione specifica, è possibile specificare un numero di versione tramite uno dei seguenti:

• rest-version query parameter
• Rest-Version header.

Dettagli del servizio REST

In questa sezione sono elencate tutte le raccolte di risorse disponibili.

Per ogni collezione sono specificate le seguenti informazioni:

• Resource: nome della risorsa
• Source: modulo sorgente IRIS (RM, AP, IR)
• Endpoint: URL della collezione
• Base: contrassegno che indica la disponibilità del servizio "base"
• Full: contrassegno che indica la disponibilità del servizio "completo"
• Versioned: flag che indica la disponibilità del controllo di versione della risorsa
• Description: descrizione della risorsa.