...
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)
- Viene restituito solo un piccolo sottoinsieme di dati.
- I risultati sono divisi in pagine e ogni pagina mostra 20 risultati.
- Il numero di elementi per pagina può essere personalizzato fino a 500 ma non è consigliabile, per evitare problemi di prestazioni.
- Per modificare la divisione delle pagine, deve essere utilizzato il parametro pageSize.
- DEVE essere utilizzato per la ricerca.
- completo (identificato dal parametro ;full)
- Tutti i metadati vengono restituiti.
- DEVE essere utilizzato per recuperare informazioni dettagliate per un articolo specifico.
- Questa versione NON fornisce tutte le funzionalità di filtraggio fornite dalla controparte di base.
- 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
- 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.