API Documentation

This documentation contains in-depth information about Wijiti's DSpace REST API implementation, including a description of the REST endpoint, available parameters, examples of possible responses and, in the case of some POST and PUT methods, example requests in both JSON and XML and possible response codes (http header codes).

The DSpace REST API's returned codes and errors are covered in HTTP Response Codes.

Authentication and Authorization

The DSpace REST API uses a basic authentication mechanism of passing the username and password with each REST request, either via querystring parameters or via the request's header.

An example of passing the username and password via the querystring:

http://path/to/rest/workflows.xml?user=email@address&pass=password

Alternatively, the username and password can be passed via the request header:

curl -i -H "user:email@address" -H "pass:password" -H "Content-Type: text/xml" -X GET "http://path/to/rest/workflows.xml"

Authorization is not carried out by the REST API; rather this is controlled by the underlying DSpace core.

Communities and Collections

EndpointActionDescription
/communitiesGETLists all communities in the repository.
/communities/:id:GETGets a single community, specified by the :id: parameter.
/communities/:id:/administratorsGETLists all administrators associated with the community, specified by the :id: parameter.
/communities/:id:/logoGETGets the logo assigned to the community, specified by the id parameter.
/communities/:id:/policesGETLists all policies associated with the community, specified by the :id: parameter.
/collectionsGETLists all collections in the repository.
/collections/countGETGets a count of the total number of collections in the repository.
/collections/:id:GETGets a single collection, specified by the id parameter.
/collections/:id:/logoGETGets the logo assigned to the collection, specified by the id parameter.
/collections/:id:/itemsGETLists all the items in the collection specified by the :id: parameter.
/collections/:i:/items/countGETGets a count of the number of items in the collection identified by the :id: parameter.
/collections/:id:/policiesGETLists all policies associated with the collection, specified by the :id: parameter.
/collections/:id:/rolesGETLists all roles associated with the collection, specified by the :id: parameter.
/communitiesPOSTCreates a new community.
/communities/:id:PUTUpdates an existing community identified by the :id: parameter.
/communities/:id:DELETEPermanently deletes the community identified by the :id: parameter. The community will only be deleted if it contains no subcommunities, collections or items.
/communities/:id:/administratorsPOSTCreates a new COMMUNITY_:id:_ADMIN group for the community, specified by the :id: parameter, and assigns the policy "ADMIN" to it.
/communities/:id:/administratorsDELETERemoves the COMMUNITY_:id:_ADMIN group from the community, specified by the :id: parameter.
/communities/:id:/logoPOSTAdds a logo to the community, specified by the :id: parameter.
/communities/:id:/logoDELETEDeletes a logo from the community, specified by the :id: parameter.
/collectionsPOSTCreates a new collection.
/collections/:id:PUTUpdates an existing collection identified by the :id: parameter.
/collections/:id:DELETEPermanently deletes the collection identified by the :id: parameter. The collection will only be deleted if it contains no items.
/collections/:id:/rolesPOSTCreates a new COLLECTION_:id:_<action> group for the collection, specified by the :id: parameter, and assigns the correct action to it.
/collections/:id:/rolesDELETERemoves the COLLECTION_:id:_<action> group from the collection, specified by the :id: parameter.
/collections/:id:/logoPOSTAdds a logo to the collection, specified by the :id: parameter.
/collections/:id:/logoDELETEDeletes a logo from the collection, specified by the :id: parameter.

Items and Bitstreams

EndpointActionDescription
/itemsGETLists all items in the repository.
/items/metadatafieldsGETLists all the available metadata fields.
/items/:id:GETGet a single item, specified by the id parameter.
/items/:id:/bundlesGETLists the bundle of bitstreams attached to the item specified by the :id: parameter.
/bitstreams/:id:GETGets a single bitstream, specified by the :id: parameter.
/bitstreams/:id:/downloadGETDownloads a single bitstream file, specified by the :id: parameter.
/itemsPOSTSubmits a new item to the repository.
/items/:id:/metadataPOSTAdds a new metadata field/value to the item.
/items/:id:/metadataPUTUpdates an item's existing metadata field/value identified by the :metadataid: parameter.
/items/:id:DELETEPermanently deletes an item from the archive, identified by the :id: parameter.
/bitstreams/:id:DELETEPermanently deletes a bitstream from the archive, identified by the :id: parameter.
/items/:id:/metadata/:metadataid:DELETEPermanently deletes a metadata field, specified by the :metadataid: parameter, from the item identified by the :id: parameter.

Users and Groups

EndpointActionDescription
/groupsGETLists all groups in the repository.
/groups/:id:GETGet a single group, specified by the id parameter.
/groups/:id:/groupsGETLists all groups which are members of the group specified by the :id: parameter.
/groups/:id:/usersGETLists all users who are members of the group specified by the :id: parameter.
/usersGETLists all users in the repository.
/users/countGETGets a count of all users in the repository.
/users/:id:GETGet a single user, speicified by the id parameter.
/groupsPOSTAdds a new group to the repository.
/groups/:id:PUTUpdates an existing group, specified by the :id: parameter.
/groups/:id:DELETEPermanently deletes a group. The group must not have any members.
/groups/:id:/groupsPUTAdd an existing group to the group, specified by the :id: parameter.
/groups/:id:/groups/:groupId:DELETEDrops a group, specified by :groupId: from the group identified by :id:.
/groups/:id:/usersPUTAdd an existing user to the group, specified by the :id: parameter.
/groups/:id:/users/:userId:DELETEDrops a user, specified by :userId: from the group identified by :id:.
/usersPOSTAdds a new user to the repository.
/users/:id:PUTUpdates an existing user, identified by the :id: parameter.
/users/:id:DELETEPermanently deletes a user, identified by the :id: parameter. If the user has added items to the repository, their items must be reassigned to another user before they can be deleted.
/users/authenticatePOSTAuthenticate a user's credentials.

Workflows

EndpointActionDescription
/submissionsGETLists incomplete submissions and items rejected from the workflow.
/submissions/countGETGets a count of the total number of the user's submissions.
/workflowsGETLists all items in the workflow pool.
/workflows/countGETGets a count of the total number of workflows.
/workflows/:id:GETGet a single workflow item, specified by the id parameter.
/workflows/:id:/acceptPUTAccept a submission awaiting review.
/workflows/:id:/approvePUTApprove a submission under review.
/workflows/:id:/rejectPUTReject an item under review.
/workflows/:id:/returnToPoolPUTReturn an item under review back to the workflow pool.

Searching and Statistics

EndpointActionDescription
/discoverGETExecutes searches directly against the repository's Solr server.
/searchGETLists items found according to a query.
/harvestGETLists items that have been created, modified or withdrawn within specified time range.
/statisticsGETLists statistical information about the repository.