Versions Compared

Old Version 14

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version Current

changes.mady.by.user Bram Luyten (Atmire)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: token expiration info

...

MethodEndpointDescription
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.

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 -

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

Example Response:
{"okay":true,"authenticated":true,"email":"admin@dspace.org","fullname":"DSpace Administrator","token":"f2f478e2-90f2-4e77-a757-4e838ae94154"}

...

  • GET /collections - Return all collections of DSpace in arrayarray. 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) and offset 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.

...

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.

...

{"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"} 


Introduction to Jersey for developers

...

  • @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

Propertystats
Example Valuetrue
Informational NoteBoolean 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.

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:

...

languagexml
  • /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

Propertystats
Example Valuetrue
Informational NoteBoolean 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).

...