Page History
...
Another thing to note is that there are Query Parameters that you can tack on to the end of an endpoint to do extra things. The most commonly used one in this API is "?expand". Instead of every API call defaulting to giving you every possible piece of information about it, it only gives a most commonly used set by default and gives the more "expensive" information when you deliberately request it. Each endpoint will provide a list of available expands in the output, but for getting started, you can start with ?expand=all, to make the endpoint provide all of its information (parent objects, metadata, child objects). You can include multiple expands, such as: ?expand=collections,subCommunities .
Pagination
Anchor | ||||
---|---|---|---|---|
|
DSpace 6.x supports pagination by allowing two query parameters: limit
and offset
. Note however that the aggregate results number is not supplied (see DS-3887). Endpoints which return arrays of objects, such as /communities, /collections or /items, are "paginated": the full list is broken into "pages" which start at offset
from the beginning of the list and contain at most limit
elements. By repeated queries you can retrieve any portion of the array or all of it. The default value of offset
is 0 and the default value of limit
is 100. So, as an example, to retrieve the sixth through tenth elements of the full list of Collections, you could do this:
...
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:
|
...
Communities in DSpace are used for organization and hierarchy, and are containers that hold sub-Communities and Collections . (ex: Department of Engineering)
...
.
For an alternative way to create a Community/Collection hierarchy to the REST API take a look at Importing Community and Collection Hierarchy.
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 a community object data type. | |
POST | /communities/{ |
...
community id}/collections |
...
Create a new collections in the specified community. You must post |
...
collection object data type. | |
POST | /communities/{ |
...
community id}/communities |
...
Create a new |
...
sub-community in the specified community. You must post |
...
a community object data type. | |
PUT | /communities/{ |
...
community id} |
...
Update the specified community. You must put |
...
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. |
Collections
Collections in DSpace are containers of Items. (ex: Engineering Faculty Publications).
For an alternative way to create a Community/Collection hierarchy to the REST API take a look at Importing Community and Collection Hierarchy.
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 an |
...
item object data type. | |
POST | /collections/find-collection |
...
Find collection by passed name. Returns the first exact match or nothing. | |
PUT | /collections/{ |
...
collection id} | Update the specified collection. You must 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. |
Items
Items in DSpace represent a "work" and combine metadata and files, known as Bitstreams.
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 a |
...
...
POST | /items/{item id}/metadata |
...
Add metadata to the specified item. You must 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 |
...
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 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. |
Bitstreams
Bitstreams are files. They have a filename, size (in bytes), and a file format. Typically in DSpace, the Bitstream will the "full text" article, or some other media. Some files are the actual file that was uploaded (tagged with bundleName:ORIGINAL), others are DSpace-generated files that are derivatives or renditions, such as text-extraction, or thumbnails. You can download files/bitstreams. DSpace doesn't really limit the type of files that it takes in, so this could be PDF, JPG, audio, video, zip, or other. Also, the logo for a Collection or a Community, is also a 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 a |
...
resourcepolicy object data type. | |
PUT | /bitstreams/{bitstream id}/data |
...
Update the data/file of the specified bitstream. You must put the data. | |
PUT | /bitstreams/{bitstream id} |
...
Update metadata of the specified bitstream. You must put a Bitstream, 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. |
You can access the parent object of a Bitstream (normally an Item, but possibly a Collection or Community when it is its logo) through: /bitstreams/:bitstreamID?expand=parent
...
In DSpace, Communities, Collections, and Items typically get minted a Handle Identifier. You can reference these objects in the REST API by their handle, as opposed to having to use the internal item-ID.
HTTP method | REST endpoint | Description |
---|---|---|
GET | /handle/{handle |
...
prefix}/{handle |
...
suffix} |
...
Returns a Community, Collection, or Item object that matches that handle. |
Hierarchy
Assembling a full representation of the community and collection hierarchy using the communities and collections endpoints can be inefficient. Retrieve a lightweight representation of the nested community and collection hierarchy. Each node of the hierarchy contains minimal information (id, handle, name).
HTTP method | REST endpoint | Description |
---|---|---|
GET | /hierarchy |
...
Retrieve a lightweight representation of the nested community and collection hierarchy. |
Schema and Metadata Field Registry
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 |
...
GET | /registries/ |
...
metadata-fields/{field id} | Add a schema to the schema registry |
POST | /registries/schema/ |
...
Add a metadata field to the specified schema |
...
POST | /registries/ |
...
schema/{ |
...
schema_ |
...
prefix}/metadata-fields | 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 /registries/schema/{schema_id}
...
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 on demo.dspace.org or Metadata Query Tool on on demo.dspace.org.
HTTP method | REST endpoint | Description |
---|---|---|
GET | /reports |
...
Return a list of report tools built on the rest 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 |
Model - Object data types
Here are all of the data types, not all fields are necessary or supported when posting/putting content, but the output contains this information:
Community Object
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":[] } |
Collection Object
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 } |
Item Object
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" } |
Bitstream Object
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 } |
ResourcePolicy Object
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 } |
...