Versions Compared

Old Version 27

changes.mady.by.user Chiara Aurora Molinaro

Saved on

compared with

New Version 28

changes.mady.by.user Chiara Aurora Molinaro

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Introduzione

Questo è il documento di riferimento per le Application Programming Interface (API) del servizio IRIS GateWay REST.

...

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

Autenticazione e autorizzazione

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.

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.

...


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-host>/gw/rest/api/public-engagements?validation.relation=mostValidated
• https://<iris-host>/gw/rest/api/public-engagements/12345?validation.relation=mostValidated

...

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.

...

  • 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:

...

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

Gestione degli errori REST

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

...

Nei rilasci futuri, queste intestazioni saranno 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).

...

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.

...

  1. payload complessi per i quali si rimanda alla documentazione di modello (cliccare su ogni elemento del seguente elenco):
    1. Progetti
    2. Bandi di finanziamento
    3. Contratti
    4. Grandi Attrezzature
    5. Mobilità in ingresso
    6. Laboratori
    7. Terza Missione (public engagements)
    8. Gruppi di ricerca

  2. payload complessi non ricostruibili da documentazione di modello:
    1. Persone
    2. Premi
    3. Biblioteche
    4. Riviste
    5. Pubblicazioni

  3. payload semplici (assimilabili a dizionari) NON ricostruibili da documentazione di modello:
    1. SSD
    2. Macrosettori concorsuali
    3. Settori concorsuali
    4. Dipartimenti
    5. Organizzazioni esterne
    6. Facoltà
    7. Ruoli delle persone
    8. Profili delle persone

Terza missione (publicEngagement - PEN)

METODO GET 

/gw/rest/api/public-engagements

...

Code Block
themeEclipse
titleTerza Missione: Risposta FULL
linenumberstrue
collapsetrue
{
    "uid": "wfItem-17031",
    "id": 17031,
    "discriminator": "wfItem",
    "displayValue": "test terza missione",
    "year": 2018,
    "snapshot": false,
    "lastModified": "2018-04-11T17:39:16",
    "estimatedImpact": "asdasdsadsad",
    "contributorSet": [
        {
            "person": {
                "pid": "rp05200",
                "id": 5526,
                "lastName": "COGNOME",
                "idAb": "127652",
                "cf": "XXXYYY",
                "firstName": "NOME"
            },
            "role": {
                "description": "Discussant",
                "id": 87546
            }
        }
    ],
    "ownerSet": [
        {
            "person": {
                "idAb": "105031",
                "id": 505,
                "firstName": "SECONDO NOME",
                "cf": "RCLFNC61M60G535N",
                "pid": "rp00180",
                "ORCID": "0000-0002-1195-530X",
                "lastName": "COGNOME COGNOME"
            },
            "secondaryRoleSet": [
                {
                    "role": {
                        "id": 20928,
                        "code": "ownerRolePublicEngagement.manager",
                        "description": "Responsabile scientifico"
                    }
                }
            ],
            "role": {
                "description": "Organizzatore",
                "id": 87467
            }
        }
    ],
    "publicEngagementProjectLinkSet": [
        {
            "parent": {
                "description": "test terza missione arcelli nuova",
                "id": 17031
            },
            "child": {
                "description": "Mucosal Immunization-Cluster Project",
                "id": 2349
            }
        }
    ],
    "wfItemType": {
        "parentWfItemTypeSet": {
            "identifier": "PEN",
            "description": "Terza missione"
        },
        "identifier": "PEN.COMITATI",
        "code": "PEN",
        "description": "Partecipazione a comitati per la definizione di standard e norme tecniche"
    },
    "internalOrganizationUnitSet": [
        {
            "organizationUnit": {
                "id": 30955,
                "sourceId": "3499",
                "idAb": "112929",
                "description": "DIPARTIMENTO DI MEDICINA E CHIRURGIA (SCHOOL OF MEDICINE AND SURGERY)"
            },
            "role": {
                "id": 87466,
                "description": "partecipante"
            }
        },
        {
            "organizationUnit": {
                "id": 4401,
                "sourceId": "2952",
                "idAb": "110438",
                "description": "DIPARTIMENTO DI INFORMATICA, SISTEMISTICA E COMUNICAZIONE"
            },
            "role": {
                "id": 87464,
                "description": "coordinatore/organizzatore"
            }
        }
    ],
    "identifier": "PEN-0016",
    "publicEngagementLinkSet": [
        {
            "parent": {
                "id": 16765,
                "description": "BIOCCA DAY"
            },
            "child": {
                "description": "test terza missione",
                "id": 17031
            }
        }
    ],
    "wfState": {
        "id": 664,
        "description": "draft"
    },
    "partnerSet": [
        {
            "relevance": {
                "description": "nazionale",
                "id": 87469
            },
            "organizationUnit": {
                "idAb": "141090",
                "id": 38300,
                "description": "LUCAS S.R.L."
            }
        }
    ],
    "description": "descrizione clob molto lunga",
    "contributorPersonCurrentOrLastInternalOrganizationUnitSet": [
        {
            "organizationUnit": {
                "description": "DIPARTIMENTO DI MEDICINA E CHIRURGIA (SCHOOL OF MEDICINE AND SURGERY)",
                "id": 30955
            }
        }
    ],
    "geographicalImpact": {
        "id": 87472,
        "description": "regionale"
    },
    "targetDescription": "asdasdasdasd",
    "ownerPersonCurrentOrLastInternalOrganizationUnitSet": [
        {
            "organizationUnit": {
                "id": 4401,
                "description": "DIPARTIMENTO DI INFORMATICA, SISTEMISTICA E COMUNICAZIONE"
            }
        }
    ],
    "secondaryCategorySet": [
        {
            "dictionary": {
                "id": 87482,
                "description": "organizzazione di eventi pubblici"
            }
        }
    ],
    "externalFinancing": 123123123,
    "numTotalDay": 1,
    "istitutionalInitiative": false,
    "initiativeLocation": "sdfsdfsdfsdfsdf",
    "mainInternalOrganizationUnitSet": [
        {
            "organizationUnit": {
                "description": "DIPARTIMENTO DI INFORMATICA, SISTEMISTICA E COMUNICAZIONE",
                "id": 4401
            }
        }
    ],
    "websiteSet": [
        {
            "url": "asdsadasdsad",
            "description": "asdasdasdasdasd"
        }
    ],
    "startDate": "2018-04-01T00:00:00",
    "activityRecipientSet": [
        {
            "dictionary": {
                "description": "altro",
                "id": 87476
            }
        }
    ],
    "totalBudget": 123123231,
    "externalPeople": "pippo pluto",
    "evaluationToolSet": [
        {
            "dictionary": {
                "description": "focus group ",
                "id": 87477
            }
        }
    ],
    "visibleOnPortal": true,
    "secondaryInternalOrganizationUnitSet": [
        {
            "organizationUnit": {
                "id": 30955,
                "description": "DIPARTIMENTO DI MEDICINA E CHIRURGIA (SCHOOL OF MEDICINE AND SURGERY)"
            }
        }
    ],
    "evaluationEnable": true,
    "promoter": "asdasdasdasd",
    "periodicEvent": false
}



Persone

METODO GET 

/gw/rest/api/people

...


BASE OUTPUT: https://<iris-host>/gw/rest/api/people?id=12345

Premi della ricerca

METODO GET 

/gw/rest/api/prizes

...

Code Block
themeEclipse
titlePremi: risposta FULL
linenumberstrue
collapsetrue
{
    "uid": "rmItem-21",
    "id": 21,
    "discriminator": "rmItem",
    "displayValue": "Premio Nobel per la fisica",
    "lastModified": "2017-12-04T16:58:14",
    "lang": {
        "code": "ita",
        "description": "Italian",
        "id": 6523
    },
    "prizeDescriptionSet": [
        {
            "lang": {
                "code": "eng",
                "description": "English",
                "id": 5725
            },
            "awarder": "The Royal Swedish Academy of Sciences, Stockholm, Sweden",
            "name": "The Nobel Prize in Physics",
            "description": "The Nobel Prize for Physics"
        }
    ],
    "keywordSet": [
        {
            "lang": {
                "code": "eng",
                "description": "English",
                "id": 5725
            },
            "description": "physics"
        },
        {
            "lang": {
                "code": "ita",
                "description": "Italian",
                "id": 6523
            },
            "description": "fisica"
        },
        {
            "lang": {
                "code": "ita",
                "description": "Italian",
                "id": 6523
            },
            "description": "Nobel"
        }
    ],
    "country": {
        "description": "Svezia",
        "code": "SWE",
        "id": 3337
    },
    "rmItemType": {
        "description": "prize",
        "id": 2
    },
    "miurIdentifier": "2",
    "relevance": {
        "id": 26580,
        "code": "1",
        "description": "Internazionale"
    },
    "url": "http://www.nobelprize.org/nobel_prizes/physics/",
    "awarder": "Accademia Reale Svedese delle Scienze, Stoccolma",
    "description": "Premio Nobel per la fisica"
}


Biblioteche

METODO GET 

/gw/rest/api/libraries

...

Code Block
themeEclipse
titleBiblioteche: risposta FULL
linenumberstrue
collapsetrue
{
    "uid": "organizationUnit-1727",
    "id": 1727,
    "discriminator": "organizationUnit",
    "displayValue": "ex-BIBLIOTECA CENTRALE",
    "lastModified": "2015-12-30T00:00:00",
    "sourceType": "STRUTTURE",
    "sourceId": "1112",
    "idAb": "112079",
    "organizationUnitType": {
        "description": "library",
        "id": 154
    },
    "description": "ex-BIBLIOTECA CENTRALE",
    "sourceSubtype": "BIB",
    "abbreviation": "BIBLIOTECA CENTRALE"
}

Riviste

METODO GET 

/gw/rest/api/prizes

...

Parametri della query REST

parametrovaloredescrizione

*id

string

Stringa contenente l'ID dell'elemento

*pid

string

Stringa contenente l'identificatore persistente dell'elemento

*code

string

Stringa contenente il codice dell'elemento

*issn

string

Stringa contenente l'ISSN dell'elemento

nature

string

Stringa contenente il codice della natura dell'elemento

country

string

Stringa contenente il codice del paese dell'elemento

name

string

Stringa contenente la descrizione dell'elemento. Si può usare anche il carattere asterisco "*"

ESEMPI:

Per recuperare tutti gli elementi: 

...

Code Block
themeEclipse
titleRiviste: risposta FULL
linenumberstrue
collapsetrue
{
    "uid": "rmItem-54",
    "id": 54,
    "discriminator": "rmItem",
    "displayValue": "ENCYCLOPAIDEIA",
    "lastModified": "2017-04-13T11:23:14",
    "sottotitolo": "RIVISTA DI FENOMENOLOGIA, PEDAGOGIA, FORMAZIONE",
    "startYear": 1997,
    "country": "IT",
    "nature": "R",
    "publisher": "Dal 1999 l'editore è :\nBologna: CLUEB Editrice. \n\nPrecedente:\n Il Segnalibro (Torino)",
    "rmItemType": {
        "description": "journal",
        "id": 5
    },
    "description": "ENCYCLOPAIDEIA",
    "code": "E187971",
    "titolo_chiave": "ENCYCLOPAIDEIA (BOLOGNA)",
    "miurIdentifier": "E187971",
    "issn": "1590-492X",
    "abbreviato": "ENCYCLOPAIDEIA"
}


Pubblicazioni