All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
...
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.
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). It returns 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. | |||||||||
The extended tokens are generated and stored in memory, not in the database or on disk. There are no timeouts for these tokens. This means that tokens remain valid as long as DSpace is not restarted. A restart of DSpace will invalidate all extended tokens. If applications re-use a token over multiple calls, especially if they are spread over a potentially longer time window, it is highly recommended that the /status endpoint is called to guarantee that a specific token is still valid. Applications that consume the DSpace REST API have no way of telling when DSpace has been restarted. In the DSpace logs, calls with invalid tokens can often look like anonymous requests being made. | |||||||||||
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 | GET | /status | -H "Content-Type: application/json" -H " | Accept: application/json" -H "rest-dspace-token: | f2f478e21febef81- | 90f25eb6- | 4e774e76- | a757a0ea- | 4e838ae94154a5be245563a5" 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 Example Response: |
...
limit
parameter to control items per response (default 100) and offset
for paging....
As the documentation may state "You must post a ResourcePolicy" or some other object type, this means that there is a structure of data types, that your XML or JSON must be of type, when it is posted in the body.
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.
...
{"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}
...
{"okay":true,"authenticated":true,"email":"test@dspace.org","fullname":"DSpace Test User","token":"6d45daaa-7b02-4ae7-86de-a960838fae5c"}
...
@GET, which indicates that this method responds to GET http requests
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML }), this indicates that this request expects input of either JSON or XML. Another endpoint accepts HTML input.
Property | stats |
---|---|
Example Value | true |
Informational Note | Boolean value indicates whether statistics should be recorded for access via the REST API; Defaults to 'false'. |
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&xforwardedfor=xforwardedfor |
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.
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 |
---|
Property | stats |
---|---|
Example Value | true |
Informational Note | Boolean value indicates whether statistics should be recorded for access via the REST API; Defaults to 'false'. |
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&xforwardedfor=xforwardedfor |
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.
...
Additional information can be found in the README for dspace-rest, and in the GitHub Pull Request for DSpace REST (Jersey).
...