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, ...)
Per accedere all'API GEST REST deve essere utilizzata l'autenticazione di base HTTP su https.
È necessario disporre di un account specifico che 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 (JavaScript Object Notation. È un formato leggero per lo scambio di dati, facile da leggere e scrivere per gli esseri umani e facile da generare e analizzare da parte delle macchine. Si basa su un sottoinsieme del linguaggio di programmazione JavaScript, ma è un formato di testo completamente indipendente dal linguaggio. Usa convenzioni già familiari ai programmatori dei linguaggi derivati dal C.)
JSON prende origine dalla sintassi degli oggetti letterali in JavaScript. Un oggetto letterale può essere definito così:
var JSON = {
proprieta1: 'Valore',
proprieta2: 'Valore',
proprietaN: 'Valore'
}
Il contenuto trasportato dall'oggetto JSON è il PAYLOAD.
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>
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-host>/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-host>/gw/rest/api/public-engagements?validation.relation=mostValidated
• https://<iris-host>/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-host>/gw/rest/api/people/12345
• https://<iris-host>/gw/rest/api/people/id=12345 (stesso risultato di quello precedente)
• https://<iris-host>/gw/rest/api/people/pid=rp12345
• https://<iris-host>/gw/rest/api/people/idAb=67890
• https://<iris-host>/gw/rest/api/people/cf=XXXXXX00X00X000X
• https://<iris-host>/gw/rest/api/people/sourceId=xxxx
• https://<iris-host>/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-host>/gw/rest/api/people?id=12345
• https://<iris-host>/gw/rest/api/people?pid=rp12345
• https://<iris-host>/gw/rest/api/people?idAb=67890
• https://<iris-host>/gw/rest/api/people?cf=XXXXXX00X00X000X
• https://<iris-host>/gw/rest/api/people?sourceId=xxxx
• https://<iris-host>/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-host>/gw/rest/api/people?page=2
• https://<iris-host>/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.
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:
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".
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:
In questa sezione sono elencate tutte le raccolte di risorse disponibili.
Per ogni collezione sono specificate le seguenti informazioni:
Resource | Source | Endpoint | Method | Base | Full | Versioned | Description |
---|---|---|---|---|---|---|---|
Projects (Progetti di ricerca) | AP | https://<iris-host>/gw/rest/api/projects | GET | X | X | Questa collezione contiene tutti i projects (Progetti di ricerca) estratti da IRIS AP | |
Calls (Bandi di finanziamento) | AP | https://<iris-host>/gw/rest/api/calls | GET | X | X | Questa collezione contiene tutti i calls for proposal (Bandi di finanziamento) estratti da IRIS AP | |
Contracts (Contratti e convenzioni) | AP | https://<iris-host>/gw/rest/api/calls | GET | X | X | Questa collezione contiene tutti i contracts and conventions (Contratti) estratti da IRIS AP | |
Equipments (Grandi attrezzature) | RM | https://<iris-host>/gw/rest/api/equipments | GET | X | X | X | Questa collezione contiene tutti gli equipments (Grandi Attrezzature) estratti da IRIS RM |
Incoming people (Mobilità in ingresso) | RM | https://<iris-host>/gw/rest/api/incoming-people | GET | X | X | Questa collezione contiene tutti gli incoming people (Mobilità in ingresso) estratti da IRIS RM | |
Laboratories (Laboratori) | RM | https://<iris-host>/gw/rest/api/laboratories | GET | X | X | X | Questa collezione contiene tutti i laboratories (Laboratori) estratti da IRIS RM |
Libraries (Biblioteche) | RM | https://<iris-host>/gw/rest/api/libraries | GET | X | X | Questa collezione contiene tutte le libraries (Biblioteche) estratte da IRIS RM | |
People (Persone) | RM | https://<iris-host>/gw/rest/api/people | GET | X | X | Questa collezione contiene people (Personale di Ateneo) estratti da IRIS RM | |
Prizes (Premi della ricerca) | RM | https://<iris-host>/gw/rest/api/prizes | GET | X | X | Questa collezione contiene tutti i prizes (Premi della ricerca) estratti da IRIS RM | |
Public Engagements (Iniziative di Public engagements - Terza Missione) | RM | https://<iris-host>/gw/rest/api/public-engagements | GET | X | X | X | Questa collezione contiene tutti i public engagements initiatives (Iniziative di public engagements - Terza Missione) estratti da IRIS RM |
Workgroups (Gruppi di ricerca) | RM | https://<iris-host>/gw/rest/api/workgroups | GET | X | X | X | Questa collezione contiene tutti i workgroups (Gruppi di ricerca) estratti da IRIS RM |
Academic Fields (SSD PRE riforma 2000) | RM | https://<iris-host>/gw/rest/api/academic-fields | GET | X | Questa collezione contiene tutti gli academic fields (SSD pre riforma 2000) estratti da IRIS RM | ||
Academic Fields 2000 (SSD POST riforma 2000) | RM | https://<iris-host>/gw/rest/api/academic-fields-2000 | GET | X | Questa collezione contiene tutti gli academic fields (SSD post riforma 2000) estratti da IRIS RM | ||
Academic Areas (Macrosettori Concorsuali) | RM | https://<iris-host>/gw/rest/api/academic-areas | GET | X | Questa collezione contiene tutti gli academic groups (Macrosettori Concorsuali) estratti da IRIS RM | ||
Academic Groups (Settori Concorsuali) | RM | https://<iris-host>/gw/rest/api/academic-groups | GET | X | Questa collezione contiene tutti gli academic groups (Settori Concorsuali) estratti da IRIS RM | ||
Departments (Dipartimenti) | RM | https://<iris-host>/gw/rest/api/departments | GET | X | Questa collezione contiene tutti i departments of the University (Dipartimenti) estratti da IRIS RM | ||
External Organizations (Organizzazioni esterne) | RM | https://<iris-host>/gw/rest/api/external-organizations | GET | X | Questa collezione contiene tutte le organizzazioni con cui l'Università ha una collaborazione (Organizzazioni esterne) estratti da IRIS RM | ||
Faculties (Facoltà) | RM | https://<iris-host>/gw/rest/api/faculties | GET | X | Questa collezione contiene tutte le faculties (Facoltà) estratte da IRIS RM | ||
Journals (Riviste) | RM | https://<iris-host>/gw/rest/api/journals | GET | X | Questa collezione contiene tutti i journals (Riviste) estratti da IRIS RM | ||
Person roles (Ruoli delle persone) | RM | https://<iris-host>/gw/rest/api/person-roles | GET | X | Questa collezione contiene tutti i person roles (Ruoli delle persone) estratti da IRIS RM | ||
Person titles (Profili delle persone) | RM | https://<iris-host>/gw/rest/api/person-titles | GET | X | Questa collezione contiene tutti i person titles (Profili delle persone) estratti da IRIS RM | ||
Publications (Pubblicazioni) - NB: in dismissione per la fine del 2019 | AP | https://<iris-host>/gw/rest/api/publications.tmp | GET | X | Questa collezione contiene tutte le pubblicazioni (Publications) estratte da IRIS IR. |
METODI
GET
/gw/rest/api/public-engagements
Tutti i parametri segnati con asterisco "*" possono essere usati come identificatori per ottenere una singola risorsa (single resource)
Nella versione FULL, invece, sono utilizzabili solo i paramentri contrassegnati da asterisco: gli altri vengono silenziosamente ignorati.
Campi disponibili per l'ordinamento: id, pid, name, year, startDate, lastModified
Request Query Parameters
parameter | value | description |
---|---|---|
*id | a String containing the ID of the item. See response for values | |
*pid | a String containing the persistent identifier. See response for values | |
[type] | a String containing the item type. Contact IRIS helpdesk for all available types | |
validation.relation | The only allowed values are master|mostValidated|all. If not provided mostValidated is assumed. More info | |
visibleOnPortal | This parameter allows the filtering of items based on the grant given by creator.The only allowed values are true|false. If not provided, all items are returned. |This parameter allows the filtering of items based on the grant given by creator.The only allowed values are true|false. If not provided, all items are returned. | |
year | Item create year | |
wfState | a String containing the wfState of the item. See response for values | |
name | a String containing the description of the item. "*" character can be used. See response for values | |
a String containing the IRIS person id. See response for values | ||
person.idAb | a String containing the Person idAb. See response for values | |
a String containing the Person CF (Codice Fiscale). See response for values | ||
person.sourceId | a String containing the Person (for universities not using U-GOV). See response for values | |
person.pid | a String containing the Person PID (IRIS IR). See response for values | |
person.orcid | a String containing the Person ORCID. See response for values | |
person.relation | owner|contributor | This field select a specific relation for a person. This field is intended in association with other person filters like person.cf. If you don't specify this field, all kind of relation is selected. See examples. |
a String containing the department id. See response for values | ||
department.idAb | a String containing the department idAb (U-GOV). See response for values | |
department.sourceId | a String containing the department sourceId (for universities not using U-GOV). See response for values | |
department.relation | owner|contributor | This parameter allows to specify the department role: main(owner) or secondary (contributor) Only owner|contributor values are allowed. This field must be used in association with other department filters like department.idAb. If specified, only the items that match the specified department and the role are returned. If not provided, all items that match the specified department are returned. See examples. |
department.match | byPerson|byDepartment | This parameter allows to specify the department match strategy: byPerson or byDepartment Only byPerson|byDepartment values are allowed. This field must be used in association with other department filters like department.idAb. If not provided, both strategy match are used otherwise only the one specified. The "byPerson" strategy infers the current department from the person owner/contributor The "byDepartment" strategy extract the department at item creation time. See examples. |
To search all Item
https://<iris-host>/gw/rest/api/public-engagements
To search Item with ID like 123456
https://<iris-host>/gw/rest/api/public-engagements?id=123456
To search Item with miurIdentifier like 123456
https://<iris-host>/gw/rest/api/public-engagements?miurIdentifier=123456
To search Item with name like Scienze:
https://<iris-host>/gw/rest/api/public-engagements?name=Scienze
To search a public-engagements on witch its owner had a current(by person) or past (byDepartment) department id 4400
https://<iris-host>/gw/rest/api/public-engagements?department.relation=owner&department.match=byPerson&department.id=4400
available response representations: