IRIS IR 1.0.0.0 REST API documentation
This is the reference document for the REST API and resources
provided by Cineca IRIS IR. The REST APIs are developers who want to
integrate IR with other applications.
Getting started
Because the REST API is based on open standards, you can use any
web development language to access the API.
If you are using Java, however, the easiest way to get started using
the IRIS IR REST API is obtain the REST IR IRIS JAVA CLIENT and use it as a
library within your own application.
IR's REST APIs provide access to resources (data entities) via URI
paths. To use a REST API, your application will make an HTTP request
and parse the response. The IR REST API uses JSON as its communication
format, and the standard HTTP methods like GET
, PUT
,
POST
and DELETE
(see API descriptions below
for which methods are available for each resource). URIs for IR's REST
API resource have the following structure:
http://host:port/context/rest/api-version/resource-name
The current API version is 1
.
As an example, if you wanted to retrieve the JSON representation of
item 328235, you would access:
https://unidemo.iris.cineca.it:443/rest/api/v1/items/328325
Due to negative performance each request has a limit for retrived object set to 50 elements and set to MAX java int for public items (SOLR)
Expansion in the REST APIs
In order to minimise network traffic and server CPU usage, the IR
REST API sometimes uses a technique called expansion. When a REST
resource uses expansion then parts of that resource will not be
included in the JSON response unless explicitly requested. The way to
request those fragments to be included is by using the expand
query parameter.
You can use the expand
query parameter to specify a
comma-separated list of entities that you want expanded, identifying
each of them by name. For example, appending ?expand=metadata,history
to an item's URI requests the inclusion of the item metadata and item
history in the response. Continuing with our example above, we would
use the following URL to get that information for item 328325:
https://unidemo.iris.cineca.it:443/rest/api/v1/items/328325?expand=metadata,history
To discover the identifiers for each entity, look at the expand
property in the parent object. In the JSON example below, the resource
declares widgets as being expandable.
{"itemId": 328325,
"self": "/rest/api/v1/items/328325",
.....
"expand":[
"metadata",
"bitstreams",
"history",
"all"]
}
Authentication and Authorization
Authentication for REST API is HTTP Basic with using SSL.
Each request is necessary give username and password in header request that will use for http basic authentication.
For application purpose any authenticated user can operate (authorization) with
specific profile or scope and can act as another IRIS user. To do this
in each request is possible set a specific HEADER TAG:
TAG HEADER TAG VALUE
scope <ROLE_USER|ROLE_ADMIN>
on-behalf-of <username>
on-behalf-of-scope <ROLE_USER|ROLE_ADMIN>
If none scope is set the default is ROLE_USER.
Generally speaking the best way for retrieve all data is act like ROLE_ADMIN with the most powerfull user (aka restadmin)
Tag on-behalf-of is necessary only for "login as" feature. Tag on-behalf-of-scope, if not set, is ROLE_USER (default).
Index
This documents the current REST API provided by IRIS IR.
Items
Remember: Due to negative performance each request has a upper limit for retrived object set to 50 elements
Items JSON rappresentation explained:
-
field name |
description |
REST object |
"itemId" |
Item Internal ID |
"item" |
"handle" |
Handle persistent identifier |
"item" |
"lastModified" |
Last modification date (track changes to bitstreams as well, not to linked entities: people, orgunit, collection, etc.) |
"item" |
"withdrawn" |
True if the item has been logically deleted |
"item" |
"archived" |
True if the item has been completed by the submitter |
"item" |
"snapshot" |
True if the item is a snapshot taken by the histories system before a change event affect the underline item |
"item" |
"inWorkspace" |
True if the item is in workspace (bozza) |
"item" |
"inWorkFlow" |
True if the item is under workflow process |
"item" |
"inReopened" |
True if the item is reopened |
"item" |
"workFlowValidationRule" |
Workflow state (step reached, if any) |
"item" |
"simpleItemStatus" |
Item status (UNKNOWN = -1, WORKSPACE = 0, WORKFLOW = 1, DEFINITIVO = 2, WITHDRAWN = 3) |
"item" |
"earlyDraft" |
True if the item has not been completed by the submitter |
"item" |
"workFlowValidationStatus" |
Product status: draft, completed (workflow inactive), in workflow (step 1, 2 or 3), validated, rejected |
"item" |
"identifierToDisseminate" |
ItemID of the version to use for dissemination (public portal, reporting) |
"item" |
"inputFormId" |
ID of the inputform profile used to create/edit last time the item |
"item" |
"lookupValues" |
Short-cut values avaible in item metadata field (useful for not lookup detail) |
"item" |
"submitterID" |
Submitter id |
"item" |
"submitterNetID" |
Submitter id (eperson) |
"item" |
"collectionHandle" |
Primary collection handle |
"item" |
"name" |
Not used |
"item" |
"type" |
IRIS resource type |
"item" |
"self" |
Item REST discoverable URI |
"item" |
"expand" |
Expand options list |
"item" |
"submitter" |
Details about the submitter (IR Account) |
"item" |
"id" |
Submitter id |
"submitter" |
"lastName" |
Submiter last name |
"submitter" |
"firstName" |
Submitter first name |
"submitter" |
"netid" |
Submitter id (eperson) |
"submitter" |
"email" |
Submitter email |
"submitter" |
"owner" |
Details about the owner (IR Account) |
"item" |
"id" |
Owner id |
"owner" |
"lastName" |
Owner last name |
"owner" |
"firstName" |
Owner first name |
"owner" |
"netid" |
Owner id (eperson) |
"owner" |
"email" |
Owner email |
"owner" |
"collection" |
Item's primary collection |
"item" |
"name" |
Collection name |
"collection" |
"id" |
Collection id |
"collection" |
"type" |
Iris resource type |
"collection" |
"handle" |
Collection handle |
"collection" |
rest/api/v1/items
Methods
GET
rest/api/v1/items?expand&limit&offset&sort&asc
Returns a list of IRIS IR items for user authenticated or user set on on-behalf-of HEADER.
request query parameters
parameter |
value |
description |
expand
|
string
|
a String containing acceptable expand list (separated by comma). See response for values
|
limit
|
int
|
a hint as to the the maximum number of items to return in each call. Note that the IRIS server reserves the right to impose a maxResults limit that is lower than the value that a client provides, dues to lack or resources or any other condition. When this happens, your results will be truncated.
|
offset
|
int
|
the index of the first item to return (0-based). must be 0 or any positive value
|
sort
|
string
|
a String containing the field based sort (default=itemId). Value: itemId | lastModified | lookupValues_year
|
asc
|
boolean
|
a boolean value for ascending or descending sort (default=true). Value true | false
|
TAG HEADER TAG VALUE
scope <ROLE_ADMIN>
on-behalf-of <author username>
on-behalf-of-scope <ROLE_USER>
available response representations:
-
200 - application/json [
expand]
Example
{
"next": "offset=20&limit=10",
"prev": "offset=10&limit=10",
"restResourseDTOList": [
{
"itemId": 1,
"owner": {
"id": -1,
"lastName": null,
"firstName": null,
"netid": null,
"email": null
},
"lastModified": 1300185331000,
"collection": {
"name": "01.a Pubblicazione su Rivista",
"id": 58,
"type": 3,
"handle": "123456789/1"
},
"lookupValues":{
"summary":"2014",
"spage":"13",
"contextidab":null,
"contextdept":"|734|1210|",
"isbn":"9788878709706",
......
}
"submitterID": 574,
"submitterNetID": "19838",
"identifierToDisseminate": -1,
"workFlowValidationStatus": -1,
"simpleItemStatus": 0,
"workFlowValidationRule": -1,
"collectionHandle": "123456789/1",
"inputFormId": 1,
"withdrawn": false,
"archived": false,
"snapshot": false,
"inWorkFlow": false,
"inWorkspace": true,
"earlyDraft": true,
"submitter": {
"id": 574,
"lastName": "PAI NOTA",
"firstName": "AN MAIA",
"netid": "19838",
"email": "user@email.it"
},
"reopened": false,
"name": "",
"type": "items",
"self": "/rest/api/v1/items/1",
"expand": [
"metadata",
"bitstreams",
"history",
"all"
]
},
{
},
{
},
{
},
{
},
{
},
{
},
{
},
{
},
{
}
]
}
Returned item lists according query parameter if the currently authenticated user has permission to view it. Contains a partial representation of the item.
-
401 - application/json [
expand]
Returned if the currently authenticated user does not have permission to view any item in the list.
Example
{
"message": "Unauthorized attempt to access ....",
"code": "UNAUTHORIZED"
}
-
500 - application/json[
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
rest/api/v1/items/{itemid} rest/api/v1/items/{namingAuthority}/{localName}
Methods
GET
rest/api/v1/items/{itemid}?expand
rest/api/v1/items/namingAuthority}/{localName}?expand
Returns a IRIS IR item.
request query parameters
parameter |
value |
description |
expand
|
string
|
a String containing acceptable expand list (separated by comma). See response for values
|
available response representations:
-
200 - application/json [
expand]
Example
{
"itemId": 1,
"owner": {
"id": -1,
"lastName": null,
"firstName": null,
"netid": null,
"email": null
},
"lastModified": 1300185331000,
"collection": {
"name": "01.a Pubblicazione su Rivista",
"id": 58,
"type": 3,
"handle": "123456789/1"
},
"lookupValues":{
"summary":"2014",
"spage":"13",
"contextidab":null,
"contextdept":"|734|1210|",
"isbn":"9788878709706",
......
}
"submitterID": 574,
"submitterNetID": "19838",
"identifierToDisseminate": -1,
"workFlowValidationStatus": -1,
"simpleItemStatus": 0,
"workFlowValidationRule": -1,
"collectionHandle": "123456789/1",
"inputFormId": 1,
"withdrawn": false,
"archived": false,
"snapshot": false,
"inWorkFlow": false,
"inWorkspace": true,
"earlyDraft": true,
"submitter": {
"id": 574,
"lastName": "PAI NOIO",
"firstName": "ANA MIA",
"netid": "19838",
"email": "user@email.com"
},
"reopened": false,
"name": "",
"type": "items",
"self": "/rest/api/v1/items/1",
"expand": [
"metadata",
"bitstreams",
"history",
"all"
]
}
Returned item if the currently authenticated user has permission to view it. Contains a partial representation of the item.
-
401 - application/json[
expand]
Returned if the currently authenticated user does not have permission to view it.
Example
{
"message": "Unauthorized attempt to access ....",
"code": "UNAUTHORIZED"
}
-
404 - application/json[
expand]
Returned if item does not exist.
Example
{
"message": "...",
"code": "..."
}
-
500 - application/json[
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
Methods
rest/api/v1/items/{itemid}/metadata
rest/api/v1/items/{namingAuthority}/{localName}/metadata
Returns a IRIS IR metadata item. (Hashmap key- values list)
request query parameters: none
available response representations:
-
200 - application/json [
expand]
-
401 - application/json [
expand]
-
404 - application/json [
expand]
-
500 - application/json [
expand]
Methods
rest/api/v1/items/{itemid}/metadata/{metadataKey}/
rest/api/v1/items/{namingAuthority}/{localName}/metadata/{metadataKey}/
Returns a IRIS IR specific metadata key (list of value) for specified item.
request query parameters: none
available response representations:
-
200 - application/json [
expand]
-
401 - application/json [
expand]
-
404 - application/json [
expand]
-
500 - application/json [
expand]
Methods
rest/api/v1/items/{itemid}/streams
rest/api/v1/items/{namingAuthority}/{localName}/streams
Returns a IRIS IR specific bitstreams item.
request query parameters: none
available response representations:
-
200 - application/json [
expand]
-
401 - application/json [
expand]
-
404 - application/json [
expand]
-
500 - application/json [
expand]
rest/api/v1/items/{itemid}/histories rest/api/v1/items/{namingAuthority}/{localName}/histories
Methods
GET
rest/api/v1/items/{itemid}/histories
rest/api/v1/items/{namingAuthority}/{localName}/histories
Returns a IRIS IR specific bitstreams item.
request query parameters: none
available response representations:
-
200 - application/json [
expand]
Example
[
{
"date": 1430931044533,
"eventType": "item_sync",
"jsonDetails": "{\"eventType\":\"ITEM_SYNC\",\"snapshotID\":-1}",
"userString": "SURNAME, name ",
"extraInfo": null
},
{...}
]
Returned item histories if the currently authenticated user has permission to view it. Contains a full representation of the item histories.
-
401 - application/json [
expand]
Returned if the currently authenticated user does not have permission to view it.
Example
{
"message": "Unauthorized attempt to access ....",
"code": "UNAUTHORIZED"
}
-
404 - application/json [
expand]
Returned if item does not exist.
Example
{
"message": "...",
"code": "..."
}
-
500 - application/json [
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
rest/api/v1/items/search
Methods
POST
Search item by JSON search DTO
-
Sort and search Criteria DTO [
expand]
Search DTO
name |
value |
description |
expand
|
string
|
a String containing acceptable expand list (separated by comma). See response for values
|
limit
|
int
|
a hint as to the the maximum number of items to return in each call (max value=MAX JAVA INT). Note that the IRIS server reserves the right to impose a maxResults limit that is lower than the value that a client provides, dues to lack or resources or any other condition. When this happens, your results will be truncated.
|
offset
|
int
|
the index of the first item to return (0-based). must be 0 or any positive value
|
operator
|
String
|
the operator used between the search criterias. not mandatory, must be "AND" or "OR", default value is "AND".
|
searchColsCriteria
|
string
|
Search query build with following DTO criteria (values array in AND operation): [{"column","operation","value"}]. See table for values
|
sortingColsCriteria
|
string
|
Sort criteria DTO: {"column","asc":}. See table for column value
|
Possible single clause value
column |
operation accepted |
value |
sort |
description |
snapshot |
= |
int (0,1) |
no |
If snapshot=1, item is a history version of latest item |
handle |
= |
string (item handle) |
no |
Handle value of item |
itemId |
= |
int (item id) |
yes |
Id value of item |
lastModified |
= < > <= >= |
date (GG/MM/AAAA) | date time (GG/MM/AAAA HH:MM:SS) |
yes |
Date of item last modified |
collectionId |
= |
int (collection id) |
yes |
Collection id of item |
workFlowValidationStatus |
= |
int (VALIDATION STP 3=5,VALIDATION STP 2=4, VALIDATION STP 1=3, REJECT=2, VALIDATE=1, INACTIVE=0, WORKSPACE=-1) |
no |
Item workflow status |
withdrawn |
= |
int (0,1) |
no |
If withdrawn = 1, item is deleted (logical delete) |
rowcreationts |
= < > <= >= |
date (GG/MM/AAAA) |
no |
Date of item create |
lookupValues_year |
= < > <= >= |
date (GG/MM/AAAA) | year (AAAA) |
yes |
item's publish date or year |
lookupValues_contextuser |
= |
string (cris id) |
no |
Cris id of item's author |
lookupValues_contextdept |
= |
int id dept |
no |
Id of item's department |
workFlowValidationRule |
= |
int (-1,0,1) |
no |
Item workflow rule |
In searchColsCriteria property, each criteria can be append to compose a condition complicated . It will interpreted as AND logic operation between each clause.
Use Case 1: obtains paginated items modified in date interval (22-April 2015 to 29-April 2015)
{
"offset": 0,
"limit": 2,
"expand": "all",
"operator": "AND",
"searchColsCriteria": [
{
"value": "21/04/2015",
"operation": ">",
"column": "lastModified"
},
{
"value": "30/04/2015",
"operation": "<",
"column": "lastModified"
}
],
"sortingColsCriteria": [
{
"column": "lastModified",
"asc": true
}
]
}
Use Case 2: obtains paginated not deleted items published in 2014
{
"offset": 0,
"limit": 2,
"expand": "all",
"searchColsCriteria": [
{
"value": "01/01/2014",
"operation": ">=",
"column": "lookupValues_year"
},
{
"value": "31/12/2015",
"operation": "<",
"column": "lookupValues_year"
},
{
"value": "0",
"operation": "=",
"column": "withdrawn"
}
]
}
Use Case 3: obtains paginated items insert in archive in January
{
"offset": 0,
"limit": 2,
"expand": "all",
"searchColsCriteria": [
{
"value": "01/01/2015",
"operation": ">=",
"column": "rowcreationts"
},
{
"value": "31/01/2015",
"operation": "<=",
"column": "rowcreationts"
}
]
}
Use Case 4: obtains paginated items from specified author (alternative options to Search with Header)
{
"offset": 0,
"limit": 2,
"expand": "all",
"searchColsCriteria": [
{
"value": "rp21724",
"column": "lookupValues_contextuser",
"operation": "="
}
]
}
available response representations:
-
200 - application/json [
expand]
Example
{
"next": "offset=4&limit=2",
"prev": "offset=0&limit=2",
"restResourseDTOList": [
{
"itemId": 1,
"owner": {
"id": -1,
"lastName": null,
"firstName": null,
"netid": null,
"email": null
},
"lastModified": 1300185331000,
"collection": {
"name": "01.a Pubblicazione su Rivista",
"id": 58,
"type": 3,
"handle": "123456789/1"
},
"lookupValues":{
"summary":"2014",
"spage":"13",
"contextidab":null,
"contextdept":"|734|1210|",
"isbn":"9788878709706",
......
}
"submitterID": 574,
"submitterNetID": "19838",
"identifierToDisseminate": -1,
"workFlowValidationStatus": -1,
"simpleItemStatus": 0,
"workFlowValidationRule": -1,
"collectionHandle": "123456789/1",
"inputFormId": 1,
"withdrawn": false,
"archived": false,
"snapshot": false,
"inWorkFlow": false,
"inWorkspace": true,
"earlyDraft": true,
"submitter": {
"id": 574,
"lastName": "PAI NOTA",
"firstName": "AN MAIA",
"netid": "19838",
"email": "user@email.it"
},
"reopened": false,
"name": "",
"type": "items",
"self": "/rest/api/v1/items/1",
"expand": [
"metadata",
"bitstreams",
"history",
"all"
]
},
{
}
]
}
Returned item lists according query parameter if the currently authenticated user has permission to view it. Contains a partial representation of the item.
-
401 - application/json [
expand]
Returned if the currently authenticated user does not have permission to view any item in the list.
Example
{
"message": "Unauthorized attempt to access ....",
"code": "UNAUTHORIZED"
}
-
500 - application/json [
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
rest/api/v1/items/ids/search
Methods
POST
Obtain incremental item id list from start id for count value
-
Search DTO
name |
value |
description |
startId
|
int
|
Start item id
|
count
|
int
|
Counter element (result cardinality)
|
searchColsCriteria
|
string
|
Search query build with following DTO criteria (values array in AND operation): [{"column","operation","value"}]. See table for values
|
Possible single clause value
column |
operation accepted |
value |
description |
snapshot |
= |
int (0,1) |
If snapshot=1, item is a history version of latest item |
lastModified |
= < > <= >= |
date (GG/MM/AAAA) |
Date of item last modified |
lookupValues_year |
= < > <= >= |
date (AAAA) |
Date of item last modified |
Use Case 1: obtain sequential items id modified between 01/07/2012 and 30/07/2012 not snapshot
{
"startId": 1000,
"count":6,
"searchColsCriteria": [
{
"value": "01/07/2012",
"operation": ">",
"column": "lastModified"
},
{
"value": "30/07/2012",
"operation": "<",
"column": "lastModified"
},
{
"value": "0",
"operation":"=",
"column":"snapshot"
}
]
}
Use Case 2: obtain sequential items id publish in 2014 and 2015 years that are not snapshot
{
"startId": 0,
"count":6,
"searchColsCriteria": [
{
"value": "2014",
"operation": ">=",
"column": "lookupValues_year"
},
{
"value": "2015",
"operation": "<=",
"column": "lookupValues_year"
},
{
"value": "0",
"operation":"=",
"column":"snapshot"
}
]
}
available response representations:
-
200 - application/json [
expand]
Example
{
"next": 2000,
"idList": [
1001,
1002,
1003,
1004,
1005,
1006]
}
Returned item lists id according query parameter if the currently authenticated user has permission to view it. Contains a partial representation of the item.
-
401 - application/json [
expand]
Returned if the currently authenticated user does not have permission to view any item in the list.
Example
{
"message": "Unauthorized attempt to access ....",
"code": "UNAUTHORIZED"
}
-
500 - application/json [
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
Collections
rest/api/v1/collections
Methods
GET
rest/api/v1/collections?expand&limit&offset
Returns a list of IRIS IR collections.
request query parameters
parameter |
value |
description |
expand
|
string
|
a String containing acceptable expand list (separated by comma). See response for values
|
limit
|
int
|
a hint as to the the maximum number of collections to return in each call. Note that the IRIS server reserves the right to impose a maxResults limit that is lower than the value that a client provides, dues to lack or resources or any other condition. When this happens, your results will be truncated.
|
offset
|
int
|
the index of the first collection to return (0-based). must be 0 or any positive value
|
available response representations:
-
200 - application/json [
expand]
Example
{
"next": "offset=20&limit=10",
"prev": "offset=0&limit=10",
"restResourseDTOList": [
{
"parentCommunities": [ ],
"copyrightText": "",
"introductoryText": "",
"sidebarText": "",
"shortDescription": "",
"name": "Senza titolo",
"handle": "1234/608672",
"type": "collection",
"id": 121,
"expand": [
"parentCommunityList",
"license",
"logo",
"countItems",
"all"
],
"self": "/rest/api/v1/collection/121"
},
{
},
{
},
{
},
{
},
{
},
{
},
{
},
{
},
{
}
]
}
Returned collections lists according query parameter if the currently authenticated user has permission to view it. Contains a partial representation of the collection.
-
401 - application/json [
expand]
Returned if the currently authenticated user does not have permission to view any collections in the list.
Example
{
"message": "Unauthorized attempt to access ....",
"code": "UNAUTHORIZED"
}
-
500 - application/json [
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
rest/api/v1/collections/{colletionid}
Methods
GET
rest/api/v1/collections/{colletionid}?expand
Returns a IRIS IR collection.
request query parameters
parameter |
value |
description |
expand
|
string
|
a String containing acceptable expand list (separated by comma). See response for values
|
available response representations:
-
200 - application/json [
expand]
Example
{
"parentCommunities": [ ],
"copyrightText": "",
"introductoryText": "",
"sidebarText": "",
"shortDescription": "",
"name": "Senza titolo",
"handle": "1234/608672",
"type": "collection",
"id": 121,
"expand": [
"parentCommunityList",
"license",
"logo",
"countItems",
"all"
],
"self": "/rest/api/v1/collection/121"
}
Returned collection if the currently authenticated user has permission to view it. Contains a partial representation of the collection.
-
401 - application/json [
expand]
Returned if the currently authenticated user does not have permission to view it.
Example
{
"message": "Unauthorized attempt to access ....",
"code": "UNAUTHORIZED"
}
-
404 - application/json [
expand]
Returned if item does not exist.
Example
{
"message": "...",
"code": "..."
}
-
500 - application/json [
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
rest/api/v1/public/items/search
Methods
POST
Search a public item (hosted in SOLR b.e.) by JSON search DTO with SOLR query
-
Search DTO
name |
value |
description |
expand
|
string
|
a String containing acceptable expand list (separated by comma). See response for values
|
limit
|
int
|
a hint as to the the maximum number of items to return in each call (max value=MAX JAVA INT). Note that the IRIS server reserves the right to impose a maxResults limit that is lower than the value that a client provides, dues to lack or resources or any other condition. When this happens, your results will be truncated.
|
offset
|
int
|
the index of the first item to return (0-based). must be 0 or any positive value
|
solrQuery
|
string
|
Solr Query written in solr syntax
|
Some SOLR document field
name |
sample |
search.resourcetype
|
search.resourcetype:2
|
search.resourceid
|
search.resourceid:15951
|
handle
|
handle:"1234/3058"
|
withdrawn
|
withdrawn:false
|
dateIssued.year
|
dateIssued.year:[1976,1976]
|
dc.date.issued
|
dc.date.issued:["1976-01-01"]
|
dc.type.miur
|
dc.type.miur:["262"]
|
title
|
title:["Proteolytic enzymes as structural probes for ribonuclease BS-1"]
|
dc.authority.people
|
dc.authority.people:["ROSSI, Paolo"]
|
author_authority
|
author_authority:["rp05105"]
|
state_s
|
state_s:(ARCHIVE_VALIDATED OR ARCHIVE_NOT_VALIDATED) -> recupera definitivi e validati
|
Use Case 1: obtains paginated items selected by rp02822
{
"offset": 0,
"limit": 100,
"expand": "all",
"solrQuery": "item.selected:rp02822"
}
Use Case 2: obtains paginated deleted items in iso lang = eng
{
"offset": 0,
"limit": 100,
"expand": "all",
"solrQuery": "dc.language.iso:\"eng\"+withdrawn:true"
}
Use Case 3: obtains paginated items published by ROSSI PAOLO
{
"offset": 0,
"limit": 100,
"expand": "all",
"solrQuery": "dc.authority.people:\"ROSSI, PAOLO\"
}
available response representations:
-
200 - application/json [
expand]
Example
{
"next": "offset=4&limit=2",
"prev": "offset=0&limit=2",
"restResourseDTOList": [
{
"itemId": 1,
"owner": {
"id": -1,
"lastName": null,
"firstName": null,
"netid": null,
"email": null
},
"lastModified": 1300185331000,
"collection": {
"name": "01.a Pubblicazione su Rivista",
"id": 58,
"type": 3,
"handle": "123456789/1"
},
"lookupValues":{
"summary":"2014",
"spage":"13",
"contextidab":null,
"contextdept":"|734|1210|",
"isbn":"9788878709706",
......
}
"submitterID": 574,
"submitterNetID": "19838",
"identifierToDisseminate": -1,
"workFlowValidationStatus": -1,
"simpleItemStatus": 0,
"workFlowValidationRule": -1,
"collectionHandle": "123456789/1",
"inputFormId": 1,
"withdrawn": false,
"archived": false,
"snapshot": false,
"inWorkFlow": false,
"inWorkspace": true,
"earlyDraft": true,
"submitter": {
"id": 574,
"lastName": "PAI NOTA",
"firstName": "AN MAIA",
"netid": "19838",
"email": "user@email.it"
},
"reopened": false,
"name": "",
"type": "items",
"self": "/rest/api/v1/items/1",
"expand": [
"metadata",
"bitstreams",
"history",
"all"
]
},
{
}
]
}
Returned item lists according query parameter if the currently authenticated user has permission to view it. Contains a partial representation of the item.
-
500 - application/json [
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
rest/api/v1/collections/{colletionid}/items
Methods
GET
rest/api/v1/collections/{colletionid}/items?expand&limit&offset
Returns a IRIS IR collection items
request query parameters
parameter |
value |
description |
expand
|
string
|
a String containing acceptable expand list (separated by comma). See response for values
|
limit
|
int
|
a hint as to the the maximum number of collections to return in each call. Note that the IRIS server reserves the right to impose a maxResults limit that is lower than the value that a client provides, dues to lack or resources or any other condition. When this happens, your results will be truncated.
|
offset
|
int
|
the index of the first collection to return (0-based). must be 0 or any positive value
|
available response representations:
-
200 - application/json [
expand]
Example
{
"next": "offset=20&limit=10",
"prev": "offset=0&limit=10",
"restResourseDTOList": [
{
"lastModified": 1361979065000,
"itemId": 58866,
"owner": {
"id": -1,
"netid": null,
"email": null,
"lastName": null,
"firstName": null
},
"inputFormId": 3,
"withdrawn": false,
"submitterID": 22,
"collection": {
"name": "01.c Nota a sentenza",
"id": 60,
"type": 3,
"handle": "123456789/3"
},
"lookupValues":{
"summary":"2014",
"spage":"13",
"contextidab":null,
"contextdept":"|734|1210|",
"isbn":"9788878709706",
......
}
"identifierToDisseminate": -1,
"workFlowValidationStatus": -1,
"simpleItemStatus": 0,
"workFlowValidationRule": -1,
"collectionHandle": "123456789/3",
"earlyDraft": true,
"inWorkspace": true,
"inWorkFlow": false,
"archived": false,
"snapshot": false,
"submitter": {
"id": 22,
"netid": null,
"email": "batch-job@cilea.it",
"lastName": "Default",
"firstName": "Utente"
},
"reopened": false,
"name": "",
"type": "items",
"expand": [
"metadata",
"bitstreams",
"history",
"all"
],
"self": "/rest/api/v1/items/58866"
},
{
},
{
},
{
},
{
},
{
},
{
},
{
},
{
},
{
}
]
}
-
500 - application/json [
expand]
rest/api/v1/collections/{colletionid}/licenceoptions
Methods
GET
rest/api/v1/collections/{colletionid}/licenceoptions
Returns a IRIS IR collection license options. Important field is licenseTypeId
No request query parameters
available response representations:
-
200 - application/json [
expand]
Example
[
{
"licenseImage": "https://i.creativecommons.org/l/by-nc-sa/3.0/it/88x31.png",
"licenseId": "standard",
"licenseUri": "http://creativecommons.org/licenses/by-nc-sa/3.0/it/",
"licenseTypeId": 137,
"licenseTitle": "Attribuzione - Non commerciale - Condividi allo stesso modo 3.0 Italia"
},
{}
]
-
500 - application/json [
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
rest/api/v1/collections/{colletionid}/embargoptions
Methods
GET
rest/api/v1/collections/{colletionid}/embargoptions
Returns a IRIS IR collection embargo options. Important field is optionName
No request query parameters
available response representations:
-
200 - application/json [
expand]
Example
[
{
"dropdownDate": null,
"requestedDate": false,
"groupName": "Anonymous",
"groupId": 0,
"optionName": "openAccess",
"dateLimit": null
},
{}
]
-
500 - application/json [
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
Communities
rest/api/v1/communities/{communityid}
Methods
GET
rest/api/v1/communities/{communityid}?expand
Returns a IRIS IR collection.
request query parameters
parameter |
value |
description |
expand
|
string
|
a String containing acceptable expand list (separated by comma). See response for values
|
available response representations:
-
200 - application/json [
expand]
Example
{
"copyrightText": "",
"introductoryText": "",
"sidebarText": "",
"shortDescription": "",
"collections": [ ],
"subcommunities": [ ],
"name": "Catalogo Ricerca UNIROMA1",
"handle": "123456789/58",
"type": "community",
"id": 16,
"expand": [
"parentCommunity",
"collections",
"logo",
"all"
],
"self": "/rest/api/v1/community/16"
}
Returned collection if the currently authenticated user has permission to view it. Contains a partial representation of the collection.
-
401 - application/json [
expand]
Returned if the currently authenticated user does not have permission to view it.
Example
{
"message": "Unauthorized attempt to access ....",
"code": "UNAUTHORIZED"
}
-
404 - application/json [
expand]
Returned if item does not exist.
Example
{
"message": "...",
"code": "..."
}
-
500 - application/json [
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
Bitstreams
rest/api/v1/streams
Methods
GET
rest/api/v1/collections?expand&limit&offset
Returns a list of IRIS IR bitstreams.
request query parameters
parameter |
value |
description |
expand
|
string
|
a String containing acceptable expand list (separated by comma). See response for values
|
limit
|
int
|
a hint as to the the maximum number of bitstreams to return in each call. Note that the IRIS server reserves the right to impose a maxResults limit that is lower than the value that a client provides, dues to lack or resources or any other condition. When this happens, your results will be truncated.
|
offset
|
int
|
the index of the first collection to return (0-based). must be 0 or any positive value
|
available response representations:
-
200 - application/json [
expand]
Example
{
"next": "offset=20&limit=10",
"priv": "offset=0&limit=10",
"restResourseDTOList": [
{
"format": "Microsoft Word",
"description": "Documento in Pre-print",
"mimeType": "application/msword",
"bundleName": "ORIGINAL",
"checkSum": {
"value": "49e989543a837b4acda692875b4704f7",
"checkSumAlgorith": "MD5"
},
"sizeBytes": 33792,
"sequenceId": 1,
"retrieveLink": "/streams/33155/attachment",
"name": "?? ??? ??? ???????.doc",
"type": "bitstream",
"id": 33155,
"expand": [
"parent",
"licenseType",
"all"
],
"self": "/rest/api/v1/streams/33155"
},
{
},
{
},
{
},
{
},
{
},
{
},
{
},
{
},
{
}
]
}
Returned bitstreams lists according query parameter if the currently authenticated user has permission to view it. Contains a partial representation of the bitstream.
-
401 - application/json [
expand]
Returned if the currently authenticated user does not have permission to view any collections in the list.
Example
{
"message": "Unauthorized attempt to access ....",
"code": "UNAUTHORIZED"
}
-
500 - application/json [
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
rest/api/v1/streams/{bitstreamid}
Methods
GET
rest/api/v1/streams/{bitstreamid}?expand
Returns a IRIS IR bitstream.
request query parameters
parameter |
value |
description |
expand
|
string
|
a String containing acceptable expand list (separated by comma). See response for values
|
available response representations:
-
200 - application/json [
expand]
Example
{
"format": "Microsoft Word XML",
"mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"bundleName": "ORIGINAL",
"checkSum": {
"value": "483f576cad8cf323b8e9a592b828ed70",
"checkSumAlgorith": "MD5"
},
"sizeBytes": 165769,
"sequenceId": 1,
"retrieveLink": "/streams/60046/attachment",
"name": "1.+Desktop+prodotti.docx",
"type": "bitstream",
"id": 60046,
"expand": [
"parent",
"licenseType",
"all"
],
"self": "/rest/api/v1/streams/60046"
}
Returned collection if the currently authenticated user has permission to view it. Contains a partial representation of the collection.
-
401 - application/json [
expand]
Returned if the currently authenticated user does not have permission to view it.
Example
{
"message": "Unauthorized attempt to access ....",
"code": "UNAUTHORIZED"
}
-
404 - application/json [
expand]
Returned if item does not exist.
Example
{
"message": "...",
"code": "..."
}
-
500 - application/json [
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
rest/api/v1/streams/{bitstreamid}/attachment
Methods
GET
rest/api/v1/streams/{bitstreamid}/attachment
Returns a IRIS IR bitstream attachment
request query parameters: none
available response representations:
Ance
rest/api/v1/ance/{crisid}
Methods
GET
rest/api/v1/ance/{crisid}
Returns a IRIS IR ance series/journal.
request query parameters: no
available response representations:
-
200 - application/json [
expand]
Example
{
"casaEditrice": "cairo: Hindawi Publishing Corporation",
"codice": "E196800",
"natura": null,
"validoAl": null,
"validoDal": "2008",
"dateSent": null,
"titoli": {
"titolo": [
{
"value": "INTERNATIONAL JOURNAL OF GEOPHYSICS",
"type": null
}
]
},
"issn": "1687-885X",
"paese": null,
"submitter": null,
"eissn": null,
"lingua": null,
"codiceCRIS": "journal25345"
}
Returned ance j/s if the currently authenticated user has permission to view it. Contains a full representation of the ance j/s.
-
401 - application/json [
expand]
Returned if the currently authenticated user does not have permission to view it.
Example
{
"message": "Unauthorized attempt to access ....",
"code": "UNAUTHORIZED"
}
-
404 - application/json [
expand]
Returned if item does not exist.
Example
{
"message": "...",
"code": "..."
}
-
500 - application/json [
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
rest/api/v1/ance/search
Methods
POST
Search ance j/s by JSON ance search DTO
-
Example
{
"crisId":"journal25345"
}
Example
{
"anceId":"E196800"
}
available response representations:
-
200 - application/json [
expand]
Example
{
"casaEditrice": "cairo: Hindawi Publishing Corporation",
"codice": "E196800",
"natura": null,
"validoAl": null,
"validoDal": "2008",
"dateSent": null,
"titoli": {
"titolo": [
{
"value": "INTERNATIONAL JOURNAL OF GEOPHYSICS",
"type": null
}
]
},
"issn": "1687-885X",
"paese": null,
"submitter": null,
"eissn": null,
"lingua": null,
"codiceCRIS": "journal25345"
}
Returned item lists according query parameter if the currently authenticated user has permission to view it. Contains a partial representation of the item.
-
401 - application/json [
expand]
Returned if the currently authenticated user does not have permission to view any item in the list.
Example
{
"message": "Unauthorized attempt to access ....",
"code": "UNAUTHORIZED"
}
-
500 - application/json [
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
Authority
rest/api/v1/authorities/{metadata_key}/
Methods
GET
rest/api/v1/authorities/{metadata_key}/?value={value}
Returns a IRIS IR decode authority values
request query parameters
parameter |
value |
description |
metadata_key
|
string
|
the name of the authority metadata (Examples: dc.authority.people, dc.authority.project, dc.authority.ancejournal, dc.authority.academicField2000, dc.authority.anceserie, dc.authority.orgunit, dc.authority.advisor, dc.authority.researchcenter, dc.authority.phdCourse, dc.authority.isicrui)
|
value
|
string
|
a String for value search
|
strategy
|
enum
|
BEST|MATCH
|
Example
https://unidemo.iris.cineca.it:443/rest/api/v1/authorities/dc.authority.people/?value=ROSSI
https://unidemo.iris.cineca.it:443/rest/api/v1/authorities/dc.authority.academicField2000/?value=CHIM/05
https://unidemo.iris.cineca.it:443/rest/api/v1/authorities/dc.authority.academicField2000/?value=Scienza%20E%20Tecnologia%20Dei%20Materiali
https://unidemo.iris.cineca.it:443/rest/api/v1/authorities/dc.authority.phdCourse/?value=87R
available response representations:
-
200 - application/json [
expand]
Example
[
{
"value": "Settore MAT/03 - Geometria",
"authority": "academicField200022180",
"label": "Settore MAT/03 - Geometria"
}
]
Returned a list of possible value match for {metadata_key} authority name
-
401 - application/json [
expand]
Returned if the currently authenticated user does not have permission to view it.
Example
{
"message": "Unauthorized attempt to access ....",
"code": "UNAUTHORIZED"
}
-
404 - application/json [
expand]
Returned if authority is not valid.
Example
{
"message": "...",
"code": "..."
}
-
500 - application/json [
expand]
Returned if was any server error type.
Example
{
"message": ".....",
"code": "...."
}
Persons
rm/restservices/api/v1/personsbyrpid/{crisid}
rm/restservices/api/v1/personsbycf/{cf}
rm/restservices/api/v1/personsbyid/{id}
Methods
GET
rm/restservices/api/v1/personsbyrpid/{crisid}
rm/restservices/api/v1/personsbycf/{cf}
rm/restservices/api/v1/personsbyid/{id}
Returns a IRIS RM person.
request query parameters: no
available response representations:
-
200 - application/json [
expand]
Example
{
"type" : "person",
"uniqueIdentifier" : "f1dbaf09-1524-49f5-a656-12db9be939a1",
"uuid" : "f1dbaf09-1524-49f5-a656-12db9be939a1",
"id" : 11803,
"crisId" : "rp11042",
"firstName" : "MAURO",
"lastName" : "DONATO",
"addressSet" : [ {
"temporary" : false,
"id" : 53709,
"discriminator" : "residenza",
"description" : "VIA SEN, 730",
"postalCode" : "40136",
"country" : {
"uniqueIdentifier" : "4537870a-89e3-452a-9389-bfcbb773359c",
"uuid" : "4537870a-89e3-452a-9389-bfcbb773359c",
"displayValue" : "Italia"
},
"place" : {
"uniqueIdentifier" : "79a7a5df-e06f-4ba6-9ce4-2dadf1559cd5",
"uuid" : "79a7a5df-e06f-4ba6-9ce4-2dadf1559cd5",
"displayValue" : "Bologna"
},
"displayValue" : "Via Sen, 730 - 40136 Bologna - Italia"
} ],
"contactSet" : [ {
"temporary" : false,
"id" : 16464,
"discriminator" : "mail",
"description" : "mauro@libero.it",
"principal" : true
}, {
"temporary" : false,
"id" : 16465,
"discriminator" : "phone",
"description" : "347",
"principal" : true
} ],
"personElementSet" : [ {
"temporary" : false,
"discriminator" : "codiceFiscale",
"gaDictionaryMap" : [ ],
"organizationUnitMap" : [ ],
"personMap" : [ ],
"stringMap" : [ {
"key" : "description",
"value" : "DDRA6723H5"
} ],
"booleanMap" : [ ],
"integerMap" : [ ],
"numberMap" : [ ],
"dateMap" : [ {
"key" : "startDate",
"value" : "1967-01-23T00:00:00"
} ],
"clobMap" : [ ]
} ],
"parentPersonLinkElementSet" : [ ],
"childPersonLinkElementSet" : [ ],
"dateMap" : [ {
"key" : "birthDate",
"value" : "1967-01-23T00:00:00"
} ],
"gaDictionaryMap" : [ {
"key" : "gender",
"value" : {
"uniqueIdentifier" : "2fe85a67-b91e-4e9b-ae5b-3eb7326b322d",
"uuid" : "2fe85a67-b91e-4e9b-ae5b-3eb7326b322d",
"id" : 1041,
"displayValue" : "Maschile"
}
}, {
"key" : "birthPlaceId",
"value" : {
"uniqueIdentifier" : "79a7a5df-e06f-4ba6-9ce4-2dadf1559cd5",
"uuid" : "79a7a5df-e06f-4ba6-9ce4-2dadf1559cd5",
"displayValue" : "Roma"
}
}, {
"key" : "birthCountryId",
"value" : {
"uniqueIdentifier" : "4537870a-89e3-452a-9389-bfcbb773359c",
"uuid" : "4537870a-89e3-452a-9389-bfcbb773359c",
"displayValue" : "Italia"
}
} ]
}
Returned person if the currently authenticated user has permission to view it. Contains a full representation of the person.
-
404 - application/json [
expand]
Returned if person does not exist.
rm/restservices/api/v1/personsbyid/{id}/positions
rm/restservices/api/v1/personsbycf/{cf}/positions
rm/restservices/api/v1/personsbyrpid/{crisid}/positions
Methods
GET
rm/restservices/api/v1/personsbyid/{id}/positions
rm/restservices/api/v1/personsbyrpid/{crisid}/positions
rm/restservices/api/v1/personsbycf/{cf}/positions
Returns a IRIS RM person careers.
request query parameters: no
available response representations:
-
200 - application/json [
expand]
Example
{
"items" : [ {
"type" : "positionCurrent",
"temporary" : false,
"discriminator" : "research",
"startDate" : "2006-03-01T00:00:00",
"endDate" : "2000-10-31T00:00:00",
"organizationUnit" : {
"uniqueIdentifier" : "9ec8dd05-eb0e-4894-9569-0b8382b6907d",
"uuid" : "9ec8dd05-eb0e-4894-9569-0b8382b6907d",
"id" : 883,
"description" : "Ricercatori Universitari",
"displayValue" : "Ricercatori Universitari",
"startDate" : "1900-01-01T00:00:00",
"organizationUnitType" : {
"displayValue" : "Qualifica (ricerca)"
},
"gaSourceIdentifiers" : [ {
"destinationId" : 883,
"destinationTable" : "GA.ORG_UNIT",
"id" : 31355,
"sourceId" : "RU",
"sourceTable" : "UGOV.RU.RUOLO"
} ]
},
"positionType" : {
"uniqueIdentifier" : "c14bcc89-9f27-4bbb-902c-b20600ac5c3b",
"uuid" : "c14bcc89-9f27-4bbb-902c-b20600ac5c3b",
"id" : 882,
"description" : "Ricercatori",
"displayValue" : "Ricercatori",
"startDate" : "1900-01-01T00:00:00",
"organizationUnitType" : {
"displayValue" : "Ruolo (ricerca)"
},
"gaSourceIdentifiers" : [ {
"destinationId" : 882,
"destinationTable" : "GA.ORG_UNIT",
"id" : 31354,
"sourceId" : "2",
"sourceTable" : "UGOV.RU.TIPO_RUOLO"
} ]
}
},{....}
]
}
Returned person careers if the currently authenticated user has permission to view it. Contains a full representation of the person career.
-
404 - application/json [
expand]
Returned if person does not exist or does not have a careers.
rm/restservices/api/v1/personsbyid/{id}/positioncurrent
rm/restservices/api/v1/personsbycf/{cf}/positioncurrent
rm/restservices/api/v1/personsbyrpid/{crisid}/positioncurrent
Methods
GET
rm/restservices/api/v1/personsbyid/{id}/positioncurrent
rm/restservices/api/v1/personsbycf/{cf}/positioncurrent
rm/restservices/api/v1/personsbyrpid/{crisid}/positioncurrent
Returns a IRIS RM person current career.
request query parameters: no
available response representations:
-
200 - application/json [
expand]
Example
{
"items" : [ {
"type" : "positionCurrent",
"temporary" : false,
"discriminator" : "research",
"startDate" : "2006-03-01T00:00:00",
"organizationUnit" : {
"uniqueIdentifier" : "9ec8dd05-eb0e-4894-9569-0b8382b6907d",
"uuid" : "9ec8dd05-eb0e-4894-9569-0b8382b6907d",
"id" : 883,
"description" : "Ricercatori Universitari",
"displayValue" : "Ricercatori Universitari",
"startDate" : "1900-01-01T00:00:00",
"organizationUnitType" : {
"displayValue" : "Qualifica (ricerca)"
},
"gaSourceIdentifiers" : [ {
"destinationId" : 883,
"destinationTable" : "GA.ORG_UNIT",
"id" : 31355,
"sourceId" : "RU",
"sourceTable" : "UGOV.RU.RUOLO"
} ]
},
"positionType" : {
"uniqueIdentifier" : "c14bcc89-9f27-4bbb-902c-b20600ac5c3b",
"uuid" : "c14bcc89-9f27-4bbb-902c-b20600ac5c3b",
"id" : 882,
"description" : "Ricercatori",
"displayValue" : "Ricercatori",
"startDate" : "1900-01-01T00:00:00",
"organizationUnitType" : {
"displayValue" : "Ruolo (ricerca)"
},
"gaSourceIdentifiers" : [ {
"destinationId" : 882,
"destinationTable" : "GA.ORG_UNIT",
"id" : 31354,
"sourceId" : "2",
"sourceTable" : "UGOV.RU.TIPO_RUOLO"
} ]
}
},{....}
]
}
Returned person current career if the currently authenticated user has permission to view it. Contains a full representation of the person career.
-
404 - application/json [
expand]
Returned if person does not have a current career.