Page History
...
Method | Endpoint | Description | ||||||
---|---|---|---|---|---|---|---|---|
GET | / | REST API static documentation page listing available endpoints and their function. Example: | ||||||
POST | /login | Login to the REST API using a DSpace EPerson (user). It returns a Example Request:
Example Response:
Example of using JSESSIONID cookie for subsequent (authenticated) requests:
Invalid email/password combinations will receive an Please note, special characters need to be HTTP URL encoded. | ||||||
GET | /shibboleth-login | Login to the REST API using Shibboleth authentication. In order to work, this requires additional Apache configuration. To authenticate, execute the following steps: 1. Call the REST Shibboleth login point with a Cookie jar:
2. This should take you again to the IdP login page. You can submit this form using curl using the same cookie jar. However this is IdP dependant so we cannot provide an example here. 3. Once you submit the form using curl, you should be taken back to the /rest/shibboleth-login URL which will return you the JSESSIONID. 4. Using that JSESSIONID, check if you have authenticated successfully:
| ||||||
POST | /logout | Logout from the REST API, by providing a Example Request:
After posting a logout request, cookie is invalidated and the "/status" path should show you as unauthenticated (even when passing that same cookie). For example:
Invalid token will result in HTTP 400 Invalid Request | ||||||
GET | /test | Returns string "REST api is running", for testing that the API is up. Example Request:
https://demo.dspace.org/rest/test Example Response:
| ||||||
GET | /status | Receive information about the currently authenticated user token, or the API itself (e.g. version information). Example Request (XML by default):
https://demo.dspace.org/rest/status Example Request (JSON):
Example JSON Response:
|
...
HTTP method | REST endpoint | Description |
---|---|---|
GET | /communities | Return an array of all the communities in the repository. The results are paginated. Example: |
GET | /communities/top-communities | Return an array of all top-level communities. The results are paginated. Example: |
GET | /communities/{community id} | Return the specified community. Example: https://demo.dspace.org/rest/communities/e97b847b-2fd5-4751-8d91-fcf0d8895b81 |
GET | /communities/{community id}/collections | Return an array of collections of the specified community. The results are paginated. |
GET | /communities/{community id}/communities | Return an array of sub-communities of the specified community. The results are paginated. |
POST | /communities | Create a new community at top level. You must post POST a community object data type. |
POST | /communities/{community id}/collections | Create a new collections in the specified community. You must post POST a collection object data type. |
POST | /communities/{community id}/communities | Create a new sub-community in the specified community. You must post POST a community object data type. |
PUT | /communities/{community id} | Update the specified community. You must put PUT a community object data type. |
DELETE | /communities/{community id} | Delete the specified community. |
DELETE | /communities/{community id}/collections/{collection id} | Delete the specified collection in the specified community. |
DELETE | /communities/{community id}/communities/{sub-community id} | Delete the specified sub-community in the specified community. |
...
HTTP method | REST endpoint | Description |
---|---|---|
GET | /collections | Return an array of all the collections in the repository. The results are paginated. |
GET | /collections/{collection id} | Return the specified collection. |
GET | /collections/{collection id}/items | Return an array all items of the specified collection. The results are paginated. |
POST | /collections/{collection id}/items | Create an item in the specified collection. You must post POST an item object data type. |
POST | /collections/find-collection | Find collection by passed name. Returns the first exact match or nothing. You must POST a single string, not a JSON object. |
PUT | /collections/{collection id} | Update the specified collection. You must put PUT a collection object data type. |
DELETE | /collections/{collection id} | Delete the specified collection. |
DELETE | /collections/{collection id}/items/{item id} | Delete the specified item in the specified collection. |
...
HTTP method | REST endpoint | Description |
---|---|---|
GET | /items | Return an array of all the items in the repository. The results are paginated. Example: |
GET | /items/{item id} | Return the specified item. |
GET | /items/{item id}/metadata | Return metadata of the specified item. |
GET | /items/{item id}/bitstreams | Return an array of all the bitstreams of the specified item. The results are paginated. |
POST | /items/find-by-metadata-field | Find items by metadata entry. You must post POST a metadataentry object data type. |
POST | /items/{item id}/metadata | Add metadata to the specified item. You must post POST an array of metadataentry object data type. |
POST/GET | /items/{item id}/bitstreams?name={file name} | Add bitstream to the specified item. You must post POST the file data and include the name parameter with the value as {file name} in the URL posted to.
description: A description of the bitstream. groupId: Id of group to set item resource policy to. year: Year to set embargo date to month: Month to set embargo date to day: Day of month to set embargo date to Example: /items/{item id}/bitstreams?name=The%20Children%27s%20Crusade%3A%20A%20Duty-Dance%20with%20Death.pdf&description=All%20this%20happened%2C%20more%20or%20less.&groupID=1969&year=2045&month=2&day=13 |
PUT | /items/{item id}/metadata | Update metadata in the specified item. You must put PUT a metadataentry object data type. Each metadata entry that will replace all prior matching metadata entries, i.e. if you submit n 'dc.subject' entries all pre-existing 'dc.subject' entries in the item will be deleted and replaced with the n entries |
DELETE | /items/{item id} | Delete the specified item. |
DELETE | /items/{item id}/metadata | Clear the metadata of the specified item. |
DELETE | /items/{item id}/bitstreams/{bitstream id} | Delete the specified bitstream of the specified bitstream. |
...
HTTP method | REST endpoint | Description |
---|---|---|
GET | /bitstreams | Return an array of all the bitstreams in the repository. The results are paginated. Example: |
GET | /bitstreams/{bitstream id} | Return the specified bitstream. |
GET | /bitstreams/{bitstream id}/policy | Return bitstream policies. |
GET | /bitstreams/{bitstream id}/retrieve | Return data of bitstream. |
POST | /bitstreams/{bitstream id}/policy | Add policy to item. You must post POST a resourcepolicy object data type. |
PUT | /bitstreams/{bitstream id}/data | Update the data/file of the specified bitstream. You must put PUT the data. |
PUT | /bitstreams/{bitstream id} | Update metadata of the specified bitstream. You must put PUT a Bitstreambitstream, does not alter the file/data. |
DELETE | /bitstreams/{bitstream id} | Delete the specified bitstream. |
DELETE | /bitstreams/{bitstream id}/policy/{policy _ id} | Delete the specified resource policy of the specified bitstream. |
...
HTTP method | REST endpoint | Description | |||
---|---|---|---|---|---|
GET | /registries/schema | Return an array of all the schema in the registry | |||
GET | /registries/schema/{schema prefix} | Return the specified schema | |||
GET | /registries/schema/{schema prefix}/metadata-fields/{element} | Return the metadata field within a schema with an unqualified element name | |||
GET | /registries/schema/{schema prefix}/metadata-fields/{element}/{qualifier} | Return the metadata field within a schema with a qualified element name | |||
GETPOST | /registries/metadata-fields/{field id}schema/ | Add a schema to the schema registry | POST | /registries/schema/ | Add a metadata field to the specified schema. You must POST a schema object data type. |
POST | /registries/schema/{schema _ prefix}/metadata-fields | Return the specified metadata field | Add a metadata field to the specified schema. You must POST a metadatafield object data type. | ||
GET | /registries/metadata-fields/{field id} | Return the specified metadata field | |||
PUT | /registries/metadata-fields/{field id} | Update the specified metadata field | |||
DELETE | /registries/metadata-fields/{field id} | Delete the specified metadata field from the metadata field registry | |||
DELETE | /registries/schema/{schema id} | Delete the specified schema from the schema registry |
Note: since the schema object contains no data fields, the following method has not been implemented: PUT PUT /registries/schema/{schema _ id}
Report Tools
Reporting Tools that allow a repository manager to audit a collection for metadata consistency and bitstream consistency. See REST Based Quality Control Reports for more information or test the Collection Report Tool or Metadata Query Tool on demo.dspace.org.
HTTP method | REST endpoint | Description |
---|---|---|
GET | /reports | Return a list of report tools built on the rest apiREST API |
GET | /reports/{nickname} | Return a redirect to a specific report |
GET | /filters | Return a list of use case filters available for quality control reporting |
GET | /filtered-collections | Return collections and item counts based on pre-defined filters |
GET | /filtered-collections/{collection _ id} | Return items and item counts for a collection based on pre-defined filters |
GET | /filtered-items | Retrieve a set of items based on a metadata query and a set of filters |
...
Anchor | ||||
---|---|---|---|---|
|
Code Block |
---|
{ "id":456, "name":"Reports Community", "handle":"10766/10213", "type":"community", "link":"/rest/communities/456", "expand":["parentCommunity","collections","subCommunities","logo","all"], "logo":null, "parentCommunity":null, "copyrightText":"", "introductoryText":"", "shortDescription":"Collection contains materials pertaining to the Able Family", "sidebarText":"", "countItems":3, "subcommunities":[], "collections":[] } |
...
Anchor | ||||
---|---|---|---|---|
|
Code Block |
---|
{ "id":730, "name":"Annual Reports Collection", "handle":"10766/10214", "type":"collection", "link":"/rest/collections/730", "expand":["parentCommunityList","parentCommunity","items","license","logo","all"], "logo":null, "parentCommunity":null, "parentCommunityList":[], "items":[], "license":null, "copyrightText":"", "introductoryText":"", "shortDescription":"", "sidebarText":"", "numberItems":3 } |
...
Anchor | ||||
---|---|---|---|---|
|
Code Block |
---|
{
"id":14301,
"name":"2015 Annual Report",
"handle":"123456789/13470",
"type":"item",
"link":"/rest/items/14301",
"expand":["metadata","parentCollection","parentCollectionList","parentCommunityList","bitstreams","all"],
"lastModified":"2015-01-12 15:44:12.978",
"parentCollection":null,
"parentCollectionList":null,
"parentCommunityList":null,
"bitstreams":null,
"archived":"true",
"withdrawn":"false"
} |
...
Anchor | ||||
---|---|---|---|---|
|
Code Block |
---|
{ "id":47166, "name":"appearance and physiology 100 percent copied from wikipedia.pdf", "handle":null, "type":"bitstream", "link":"/rest/bitstreams/47166", "expand":["parent","policies","all"], "bundleName":"ORIGINAL", "description":"", "format":"Adobe PDF", "mimeType":"application/pdf", "sizeBytes":129112, "parentObject":null, "retrieveLink":"/bitstreams/47166/retrieve", "checkSum":{"value":"62778292a3a6dccbe2662a2bfca3b86e","checkSumAlgorithm":"MD5"}, "sequenceId":1, "policies":null } |
...
Anchor | ||||
---|---|---|---|---|
|
Code Block |
---|
{ "id":317127, "action":"READ", "epersonId":-1, "groupId":0, "resourceId":47166, "resourceType":"bitstream", "rpDescription":null, "rpName":null, "rpType":"TYPE_INHERITED", "startDate":null, "endDate":null } |
MetadataEntry Object
Anchor | ||||
---|---|---|---|---|
|
Code Block |
---|
{ "key":"dc.description.abstract", "value":"This is the description abstract", "language": null } |
...
Schema Object
Anchor | ||||
---|---|---|---|---|
|
Code Block |
---|
{ "emailnamespace": "test@dspaceexample.org/myschema", "prefix": "myschema" } |
MetadataField Object
Anchor | ||||
---|---|---|---|---|
|
Code Block |
---|
{
"description" : "myschema test field",
"element" : "test",
"name" : "myschema.test",
"qualifier": null
} |
User Object
Code Block |
---|
{ "email":"test@dspace.org", "password":"password":"pass" } |
Status Object
Code Block |
---|
{
"okay":true,
"authenticated":true,
"email":"test@dspace.org",
"fullname":"DSpace Test User",
"token":"6d45daaa-7b02-4ae7-86de-a960838fae5c"
} |
...