All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
...
Example usage from command line in XML format with pretty printing:
Code Block |
---|
curl -s -H "Accept: application/xml" http://localhost:8080/rest/communities | xmllint --format - |
...
Example usage from command line in JSON format with pretty printing:
Code Block |
---|
curl -s -H "Accept: application/json" http://localhost:8080/rest/communities | python -m json.tool |
For this documentation, we will assume that the URL to the "REST" webapp will be http://localhost:8080/rest/ for production systems, this address will be slightly different, such as: http https://demo.dspace.org/rest/. The path to an endpoint, will go after the /rest/, such as /rest/communities, all-together this is: http://localhost:8080/rest/communities
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 .
...
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:
Code Block | ||
---|---|---|
| ||
curl -s -H "Accept: application/json" http://localhost:8080/rest/collections?offset=5\&limit=5 |
Note |
---|
REST API Authentication has changed in DSpace 6.x. It now uses a |
Method | Endpoint | Description | ||||||
---|---|---|---|---|---|---|---|---|
GET | / | REST API static documentation page | ||||||
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:
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):
Example Request (JSON):
Example JSON Response:
|
Before Shibboleth authentication for the REST API will work, you need to secure the /rest/shibboleth-login
endpoint. Add this configuration section to your Apache HTTPD Shibboleth configuration:
Code Block |
---|
<Location "/rest/shibboleth-login">
AuthType shibboleth
ShibRequireSession On
# Please note that setting ShibUseHeaders to "On" is a potential security risk.
# You may wish to set it to "Off". See the mod_shib docs for details about this setting:
# https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig#NativeSPApacheConfig-AuthConfigOptions
# Here's a good guide to configuring Apache + Tomcat when this setting is "Off":
# https://www.switch.ch/de/aai/support/serviceproviders/sp-access-rules.html#javaapplications
ShibUseHeaders On
require valid-user
</Location> |
You can test your configuration in 3 different ways:
...
Login to the REST API using a DSpace EPerson (user). It returns a JSESSIONID
cookie, that can be used for future authenticated requests.
Example Request:
Code Block |
---|
curl -v "https://dspace.myu.edu/rest/login?email=admin@dspace.org&password=dspace" |
Example Response:
Code Block |
---|
HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8; Path=/rest/; Secure; HttpOnly |
Example of using JSESSIONID cookie for subsequent (authenticated) requests:
...
...
Logout from the REST API, by providing a JSESSIONID
cookie. After being posted this cookie will no longer work.
...
https://dspace.myu.edu/rest/
...
Invalid email/password combinations will receive an HTTP 401 Unauthorized
response.
Please note, special characters may need to be HTTP URL encoded. For example, an email address like dspacedemo+admin@gmail.com
(notice the + special character) would need to be encoded as dspacedemo%2Badmin@gmail.com
.
shibboleth-login
, this should redirect you to the login page of your IdP if you don't have a Shibboleth session yet./rest/shibboleth-login
URL. You should then see a blank page but in the response headers, the JSESSIONID cookie should be present./rest/status
and you should see information on the current authenticated ePerson.Code Block |
---|
curl - |
...
v |
...
-L - |
...
c cookiejar "https: |
...
//dspace.myu.edu/rest/shibboleth-login" |
/rest/shibboleth-login
URL which will return you the JSESSIONID.Using that JSESSIONID, check if you have authenticated successfully:
Code Block |
---|
curl -v "https://dspace.myu.edu/dspace-rest/status" |
...
Invalid token will result in HTTP 400 Invalid Request
--cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9" |
_shibsession_64656661756c74687...
You can also grab this cookie from your browser.Double check that the cookie you took is valid
...
Returns string "REST api is running", for testing that the API is up.
...
:
Code Block |
---|
curl -v 'https://dspace |
...
Example Response:
Code Block |
---|
REST api is running. |
...
Receive information about the currently authenticated user token.
-url/Shibboleth.sso/Session' -H 'Cookie: _shibsession_64656661756c7468747470733a2f2f7265706f7369746f72792e636172646966666d65742e61632e756b2f73686962626f6c657468=_a8d3ad20d8b655250c7357f7ac0e2910;' |
Use this cookie to obtain a Tomcat JSESSIONID
...
:
Code Block |
---|
curl -v |
...
'https://dspace |
...
-url/rest/ |
...
Example Request (JSON):
Code Block |
---|
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" -v "https://dspace.myu.edu/rest/status" --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" |
Example JSON Response:
shibboleth-login' -H 'Cookie: _shibsession_64656661756c7468747470733a2f2f7265706f7369746f72792e636172646966666d65742e61632e756b2f73686962626f6c657468=_a8d3ad20d8b655250c7357f7ac0e2910;' |
Use the returned JSESSIONID to check if you have authenticated successfully:
Code Block |
---|
curl -v "http://dspace-url/rest/status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9" |
...
Communities in DSpace are used for organization and hierarchy, and are containers that hold sub-Communities and Collections. (ex: Department of Engineering)
...
...
* note that each metadata entry that you put 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
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.
...
Here are all of the data types, not all fields are necessary or supported when posting/putting content, but the output contains this information:
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":[]} |
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} |
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"} |
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} |
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}] |
Code Block |
---|
{"key":"dc.description.abstract", "value":"This is the description abstract", "language": null} |
Code Block |
---|
{"email":"test@dspace.org","password":"pass"} |
Code Block |
---|
{"okay":true,"authenticated":true,"email":"test@dspace.org","fullname":"DSpace Test User","token":"6d45daaa-7b02-4ae7-86de-a960838fae5c"} |
...
...
Property | rest.stats |
---|---|
Example Value | true |
Informational Note | Boolean value indicates whether statistics should be recorded for access via the REST API; Defaults to 'false'. |
...