All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
Page History
...
In DSpace 5, the REST API adds authentication, allows Creation, Update, and Delete to objects, can access restricted materials if authorized, and it requires SSL.
Disabling SSL
For localhost development purposes, SSL can add additional getting-started difficulty, so security can be disabled. To disable DSpace REST's requirement to require security/ssl, alter [dspace]/webapps/rest/WEB-INF/web.xml or [dspace-source]/dspace-rest/src/main/webapp/WEB-INF/web.xml and comment out the security<security-constraint constraint> block, and restart your servlet container. Production usages of the REST API should use SSL, as authentication credentials should not go over the internet unencrypted.
...
| Method | Endpoint | Description |
|---|---|---|
| GET | / | REST API static documentation page |
| POST | /login | Login to the REST API using a DSpace EPerson / User(user). It returns an dspace-rest-a token, that can be used for future authenticated requests (as a value of the rest-dspace-token request header). Example Request: curl -H "Content-Type: application/json" --data '{"email":"admin@dspace.org", "password":"dspace"}' http://localhost:8080/rest/login Example Response: 1febef81-5eb6-4e76-a0ea-a5be245563a5 Invalid email/password combinations will receive an HTTP 403 Forbidden. |
| POST | /logout | Logout from the REST API, by providing a header rest-dspace-token. After being posted this token will no longer work. Example Request: curl -X POST -H "Content-Type: application/json" -H "rest-dspace-token: 1febef81-5eb6-4e76-a0ea-a5be245563a5" http://localhost:8080/rest/logout 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: curl http://localhost:8080/rest/test Example Response: REST api is running. |
| GET | /status | Receive information about the currently authenticated user token. Example Request: curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" -H "rest-dspace-token: f2f478e2-90f2-4e77-a757-4e838ae94154" http://localhost:8080/rest/status |
...
{"id":456,"name":"Reports Community","handle":"10766/10213","type":"community","link":"/RESTapirest/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":[]}
...
{"id":730,"name":"Annual Reports Collection","handle":"10766/10214","type":"collection","link":"/RESTapirest/collections/730","expand":["parentCommunityList","parentCommunity","items","license","logo","all"],"logo":null,"parentCommunity":null,"parentCommunityList":[],"items":[],"license":null,"copyrightText":"","introductoryText":"","shortDescription":"","sidebarText":"","numberItems":3}
...
{"id":14301,"name":"2015 Annual Report","handle":"123456789/13470","type":"item","link":"/RESTapirest/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"}
...
{"id":47166,"name":"appearance and physiology 100 percent copied from wikipedia.pdf","handle":null,"type":"bitstream","link":"/RESTapirest/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}
...
For the purpose of more accurate statistics, a web-based tool may specify who is using it, by adding parameters to the request:
| Code Block |
|---|
http://localhost:8080/rest/items/:ID?userIP=ip&userAgent=userAgent&xforwarderforxforwardedfor=xforwarderforxforwardedfor |
If no parameters are given, the details of the HTTP request's sender are used in statistics. This enables tools to record the details of their user rather than themselves.
Deploying the DSpace REST API in your Servlet Container
The dspace-rest module is automatically configured to compile and build with DSpace 4.0, so a mvn+ant process will create the webapp. To make it work in your environment, you would just need to add a context entry for it in your servlet container. For example, in tomcat, one might alter $CATALINA_HOME/conf/server.xml and add:
...
| language | xml |
|---|
...
Additional Information
Additional information can be found in the README for dspace-rest, and in the GitHub Pull Request for DSpace REST (Jersey).
...
Overview
Content Tools