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
Endpoint | Action | Description |
---|---|---|
/communities | GET | Lists all communities in the repository. |
/communities/:id: | GET | Gets a single community, specified by the :id: parameter. |
/communities/:id:/administrators | GET | Lists all administrators associated with the community, specified by the :id: parameter. |
/communities/:id:/logo | GET | Gets the logo assigned to the community, specified by the id parameter. |
/communities/:id:/polices | GET | Lists all policies associated with the community, specified by the :id: parameter. |
/collections | GET | Lists all collections in the repository. |
/collections/count | GET | Gets a count of the total number of collections in the repository. |
/collections/:id: | GET | Gets a single collection, specified by the id parameter. |
/collections/:id:/logo | GET | Gets the logo assigned to the collection, specified by the id parameter. |
/collections/:id:/items | GET | Lists all the items in the collection specified by the :id: parameter. |
/collections/:i:/items/count | GET | Gets a count of the number of items in the collection identified by the :id: parameter. |
/collections/:id:/policies | GET | Lists all policies associated with the collection, specified by the :id: parameter. |
/collections/:id:/roles | GET | Lists all roles associated with the collection, specified by the :id: parameter. |
/communities | POST | Creates a new community. |
/communities/:id: | PUT | Updates an existing community identified by the :id: parameter. |
/communities/:id: | DELETE | Permanently deletes the community identified by the :id: parameter. The community will only be deleted if it contains no subcommunities, collections or items. |
/communities/:id:/administrators | POST | Creates a new COMMUNITY_:id:_ADMIN group for the community, specified by the :id: parameter, and assigns the policy "ADMIN" to it. |
/communities/:id:/administrators | DELETE | Removes the COMMUNITY_:id:_ADMIN group from the community, specified by the :id: parameter. |
/communities/:id:/logo | POST | Adds a logo to the community, specified by the :id: parameter. |
/communities/:id:/logo | DELETE | Deletes a logo from the community, specified by the :id: parameter. |
/collections | POST | Creates a new collection. |
/collections/:id: | PUT | Updates an existing collection identified by the :id: parameter. |
/collections/:id: | DELETE | Permanently deletes the collection identified by the :id: parameter. The collection will only be deleted if it contains no items. |
/collections/:id:/roles | POST | Creates a new COLLECTION_:id:_<action> group for the collection, specified by the :id: parameter, and assigns the correct action to it. |
/collections/:id:/roles | DELETE | Removes the COLLECTION_:id:_<action> group from the collection, specified by the :id: parameter. |
/collections/:id:/logo | POST | Adds a logo to the collection, specified by the :id: parameter. |
/collections/:id:/logo | DELETE | Deletes a logo from the collection, specified by the :id: parameter. |
Items and Bitstreams
Endpoint | Action | Description |
---|---|---|
/items | GET | Lists all items in the repository. |
/items/metadatafields | GET | Lists all the available metadata fields. |
/items/:id: | GET | Get a single item, specified by the id parameter. |
/items/:id:/bundles | GET | Lists the bundle of bitstreams attached to the item specified by the :id: parameter. |
/bitstreams/:id: | GET | Gets a single bitstream, specified by the :id: parameter. |
/bitstreams/:id:/download | GET | Downloads a single bitstream file, specified by the :id: parameter. |
/items | POST | Submits a new item to the repository. |
/items/:id:/metadata | POST | Adds a new metadata field/value to the item. |
/items/:id:/metadata | PUT | Updates an item's existing metadata field/value identified by the :metadataid: parameter. |
/items/:id: | DELETE | Permanently deletes an item from the archive, identified by the :id: parameter. |
/bitstreams/:id: | DELETE | Permanently deletes a bitstream from the archive, identified by the :id: parameter. |
/items/:id:/metadata/:metadataid: | DELETE | Permanently deletes a metadata field, specified by the :metadataid: parameter, from the item identified by the :id: parameter. |
Users and Groups
Endpoint | Action | Description |
---|---|---|
/groups | GET | Lists all groups in the repository. |
/groups/:id: | GET | Get a single group, specified by the id parameter. |
/groups/:id:/groups | GET | Lists all groups which are members of the group specified by the :id: parameter. |
/groups/:id:/users | GET | Lists all users who are members of the group specified by the :id: parameter. |
/users | GET | Lists all users in the repository. |
/users/count | GET | Gets a count of all users in the repository. |
/users/:id: | GET | Get a single user, speicified by the id parameter. |
/groups | POST | Adds a new group to the repository. |
/groups/:id: | PUT | Updates an existing group, specified by the :id: parameter. |
/groups/:id: | DELETE | Permanently deletes a group. The group must not have any members. |
/groups/:id:/groups | PUT | Add an existing group to the group, specified by the :id: parameter. |
/groups/:id:/groups/:groupId: | DELETE | Drops a group, specified by :groupId: from the group identified by :id:. |
/groups/:id:/users | PUT | Add an existing user to the group, specified by the :id: parameter. |
/groups/:id:/users/:userId: | DELETE | Drops a user, specified by :userId: from the group identified by :id:. |
/users | POST | Adds a new user to the repository. |
/users/:id: | PUT | Updates an existing user, identified by the :id: parameter. |
/users/:id: | DELETE | Permanently 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/authenticate | POST | Authenticate a user's credentials. |
Workflows
Endpoint | Action | Description |
---|---|---|
/submissions | GET | Lists incomplete submissions and items rejected from the workflow. |
/submissions/count | GET | Gets a count of the total number of the user's submissions. |
/workflows | GET | Lists all items in the workflow pool. |
/workflows/count | GET | Gets a count of the total number of workflows. |
/workflows/:id: | GET | Get a single workflow item, specified by the id parameter. |
/workflows/:id:/accept | PUT | Accept a submission awaiting review. |
/workflows/:id:/approve | PUT | Approve a submission under review. |
/workflows/:id:/reject | PUT | Reject an item under review. |
/workflows/:id:/returnToPool | PUT | Return an item under review back to the workflow pool. |
Searching and Statistics
Endpoint | Action | Description |
---|---|---|
/discover | GET | Executes searches directly against the repository's Solr server. |
/search | GET | Lists items found according to a query. |
/harvest | GET | Lists items that have been created, modified or withdrawn within specified time range. |
/statistics | GET | Lists statistical information about the repository. |