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.
...
curl -s -H "Accept: application/xml" http://localhost:8080/rest/communities | xmllint --format -
...
Example usage from command line in JSON format with pretty printing:
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, for production systems, this address will be slightly different, such as: http://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
...
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: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 | GET | /status | Receive information about the currently authenticated user token. Example Request: curl -X | GET POST -H "Content-Type: application/json" -H | "Accept: application/json" | -H "rest-dspace-token: | f2f478e21febef81- | 90f25eb6- | 4e774e76- | a757a0ea- | 4e838ae94154a5be245563a5" http://localhost:8080/rest/ | status
Communities
Communities in DSpace are used for organization and hierarchy, and are containers that hold sub-Communities and Collections. (ex: Department of Engineering)
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 |
Communities
Communities in DSpace are used for organization and hierarchy, and are containers that hold sub-Communities and Collections. (ex: Department of Engineering)
- GET /communities - Returns array of all communities in DSpace.
- GET /communities/top-communities - Returns array of all top communities in DSpace.
- GET /communities/{communityId} - Returns community.
- GET /communities/{communityId}/collections - Returns array of collections of community.
- GET /communities/{communityId
- GET /communities - Returns array of all communities in DSpace.
- GET /communities/top-communities - Returns array of all top communities in DSpace.
- GET /communities/{communityId} - Returns community.
- GET /communities/{communityId}/collections - Returns array of collections of community.
- GET /communities/{communityId}/communities - Returns array of subcommunities of community.
- POST /communities - Create new community at top level. You must post community.
- POST /communities/{communityId}/collections - Create new collections in community. You must post Collection.
- POST /communities/{communityId}/communities - Create new subcommunity in community. You must post Community.
- PUT /communities/{communityId} - Update community. You must put Community
- DELETE /communities/{communityId} - Delete community.
- DELETE /communities/{communityId}/collections/{collectionId} - Delete collection in community.
- DELETE /communities/{communityId}/communities/{communityId2} - Delete subcommunity in community.
...
- GET /collections - Return all collections of DSpace in array. Use the limit parameter to control items per response (default 100) and offset for paging.
- GET /collections/{collectionId} - Return collection with id.
- GET /collections/{collectionId}/items - Return all items of collection. Use the
limit
parameter to control items per response (default 100) andoffset
for paging. - POST /collections/{collectionId}/items - Create posted item in collection. You must post an Item
- POST /collections/find-collection - Find collection by passed name.
- PUT /collections/{collectionId} - Update collection. You must put Collection.
- DELETE /collections/{collectionId} - Delete collection from DSpace.
- DELETE /collections/{collectionId}/items/{itemId} - Delete item in collection.
...
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 Bitstreama Collection or a Community, is also a Bitstream.
- GET /bitstreams - Return all bitstreams in DSpace. Use the
limit
parameter to control items per response (default 100) andoffset
for paging. - GET /bitstreams/{bitstream id} - Return bitstream.
- GET /bitstreams/{bitstream id}/policy - Return all bitstreams in DSpace. Use the
limit
parameter to control items per response (default 100) andoffset
for paging.bitstream policies. - GET /bitstreams/{bitstream id}/retrieve - Return data of bitstream.
- POST /bitstreams/{bitstream id}/policy - Add policy to item. You must post a ResourcePolicy
- PUT GET /bitstreams/{bitstream id} - Return /data - Update data/file of bitstream. You must put the dataGET
- PUT /bitstreams/{bitstream id} /policy - Return Update metadata of bitstream. You must put a Bitstream, does not alter the file/data
- DELETE policies.GET /bitstreams/{bitstream id} /retrieve - Return data of Delete bitstream from DSpace.
- POST DELETE /bitstreams/{bitstream id}/policy - Add policy to item. You must post a ResourcePolicyPUT /bitstreams/{bitstream policy_id} /data - Update data/file of bitstream. You must put the data
- PUT /bitstreams/{bitstream id} - Update metadata of bitstream. You must put a Bitstream, does not alter the file/data
- DELETE /bitstreams/{bitstream id} - Delete bitstream from DSpace.
- DELETE /bitstreams/{bitstream id}/policy/{policy_id} - Delete bitstream policy.
You can access the parent object of a Bitstream (normally an Item, but possibly a Collection or Community when it is its logo) through: /bitstreams/:bitstreamID?expand=parent
...
- - Delete bitstream policy.
You can access the parent object of a Bitstream (normally an Item, but possibly a Collection or Community when it is its logo) through: /bitstreams/:bitstreamID?expand=parent
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.
Handle
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.
- GET /handle/{handle-prefix}/{handle-suffix} - Returns a Community, Collection, or Item object that matches that handle.
Model - Object data types
...
{"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}
...
{"email":"test@dspace.org","password":"pass"}
Status Object
{"okay":true,"authenticated":true,"email":"test@dspace.org","fullname":"DSpace Test User","token":"6d45daaa-7b02-4ae7-86de-a960838fae5c"}
Introduction to Jersey for developers
The REST API for DSpace is implemented using Jersey, the reference implementation of the Java standard for building RESTful Web Services (JAX-RS 1). That means this API should be easier to expand and maintain than other API approaches, as this approach has been widely adopted in the industry. If this client documentation does not fully answer about how an endpoint works, it is helpful to look directly at the Java REST API code, to see how it is implemented. The code typically has required parameters, optional parameters, and indicates the type of data that will be responded.
There was no central ProviderRegistry that you have to declare your path. Instead, the code is driven by annotations, here is a list of annotations used in the code for CommunitiesResource.java:
}
Status Object
{"okay":true,"authenticated":true,"email":"test@dspace.org","fullname":"DSpace Test User","token":"6d45daaa-7b02-4ae7-86de-a960838fae5c"}
Introduction to Jersey for developers
The REST API for DSpace is implemented using Jersey, the reference implementation of the Java standard for building RESTful Web Services (JAX-RS 1). That means this API should be easier to expand and maintain than other API approaches, as this approach has been widely adopted in the industry. If this client documentation does not fully answer about how an endpoint works, it is helpful to look directly at the Java REST API code, to see how it is implemented. The code typically has required parameters, optional parameters, and indicates the type of data that will be responded.
There was no central ProviderRegistry that you have to declare your path. Instead, the code is driven by annotations, here is a list of annotations used in the code for CommunitiesResource.java:
- @Path("/communities"), which then allows it to be routed to
- @Path("/communities"), which then allows it to be routed to http://localhost:8080/communities, this is then the base path for all the requests within this class.
@GET, which indicates that this method responds to GET http requests
- @POST, which indicates that this method responds to POST http requests
- @PUT, which indicates that this method responds to PUT http requests
- @DELETE, which indicates that this method responds to DELETE http requests
- @Path("/{community_id}"), the path is appended to the class level @Path above, this one uses a variable {community_id}. The total endpoint would be http://localhost:8080/rest/communities/123, where 123 is the ID.
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML }), this indicates that this request expects input of either JSON or XML. Another endpoint accepts HTML input.
- @PathParam("community_id") Integer communityId, this maps the path placeholder variable {community_id} to Java int communityID
- @QueryParam("userIP") String user_ip, this maps a query param like ?userIP=8.8.4.4 to Java String user_id variable, and user_id == "8.8.4.4"
Configuration for DSpace REST
Property | stats |
---|---|
Example Value | true |
Informational Note | Boolean value indicates whether statistics should be recorded for access via the REST API; Defaults to 'false'. |
Recording Proxy Access by Tools
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&xforwarderfor=xforwarderfor |
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 |
---|
- this is then the base path for all the requests within this class.
@GET, which indicates that this method responds to GET http requests
- @POST, which indicates that this method responds to POST http requests
- @PUT, which indicates that this method responds to PUT http requests
- @DELETE, which indicates that this method responds to DELETE http requests
- @Path("/{community_id}"), the path is appended to the class level @Path above, this one uses a variable {community_id}. The total endpoint would be http://localhost:8080/rest/communities/123, where 123 is the ID.
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML }), this indicates that this request expects input of either JSON or XML. Another endpoint accepts HTML input.
- @PathParam("community_id") Integer communityId, this maps the path placeholder variable {community_id} to Java int communityID
- @QueryParam("userIP") String user_ip, this maps a query param like ?userIP=8.8.4.4 to Java String user_id variable, and user_id == "8.8.4.4"
Configuration for DSpace REST
Property | stats |
---|---|
Example Value | true |
Informational Note | Boolean value indicates whether statistics should be recorded for access via the REST API; Defaults to 'false'. |
Recording Proxy Access by Tools
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
Additional information can be found in the README for dspace-rest, and in the GitHub Pull Request for DSpace REST (Jersey).
...