Presentation given at OR2019 Hamburg DSpace 7 is a major update of the DSpace platform with a new substantial different architecture than previous DSpace versions. The need to provide a fully-fledged REST API layer on top of which the new Angular (javascript) UI has been built was the opportunity to move to updated technologies, standards and best practice for the REST layer previously quickly introduced in the DSpace landscape to meet urgent needs of interoperability. Indeed, the goal of the new REST API is to meet the level 3 of the famous Richardson Maturity Model [1] allowing a client application or its developer to potentially learn how to use the API without pre-knowledge or need to consult external information. The adoption of uniform, consistent and self-documented behaviour will drastically reduce the effort for developers to interact with DSpace. Moreover, each operation that can be performed from the UI as an anonymous user or a user with whatever privilege, including repository managers and administrators, can now be done via a standard REST API. To offer a strong interoperability layer is crucial to provide a stable, well documented and fully tested solution so that integration will not easily break from one version to another: for this reason the REST development adopted a Test-Driven Development and Contract [2] first approach. The presentation will illustrate the adopted standards HATEOAS [3], HAL [4], JWT [5], ALPS [6] showing how to interact with the new REST API to get and manipulate information. Different integration scenarios will be presented explaining how the new REST API can be used to implement them. This will include reuse of the information available in DSpace in other contexts such as personal, departmental or institutional websites. Integration of DSpace in research workflows for data acquisition, embedding of the repository in wide institutional processes like ETD preparation triggering workflow automation in response of external events. Quickly prototyping end users functionalities such as notification services, reporting tools, batch processing in the language of preference of developers. The development processes and technologies [7] will also be quickly introduced as a reference to provide direction to those interested in customizing the new REST API or to participate in its future development.

1. DSpace 7: Open for Integration
Andrea Bollini, 4Science
Luigi Andrea Pascarell, 4Science
Open Repositories 2019, Hamburg, June 10-13

2. To adopt a Repository-as-a-Service model, support
different users and communities, it is crucial to be able to
interact with the repository with different, unanticipated
patterns and modalities embedding the repository in
existing workflows, connecting and combining tools.
About

3. Why a new REST API?
Covers only a subset of
DSpace functionality
Not based on current
REST best practices
or standards
Handcrafted in Jersey,
while most DSpace code uses
Spring technologies
4.x - 6.x
No search
No submit / workflows
Limited admin operations
Limited write / delete
(4.x was read only)

4. All features MUST
be in REST API
(for Angular UI)
Defined REST Contract.
HATEOAS, ALPS,
HAL format
Built using Spring technologies
(Spring Boot, MVC, HATEOAS)
Bonus: better third-party
app integration!
7.x
{ REST }
Why a new REST API?

5. REST Maturity Level
Image from: https://martinfowler.com/articles/richardsonMaturityModel.html
{ REST }
HATEOAS = Hypertext As The Engine Of Application State
Allow the client to discover the “next step”
HAL = Hypertext Application Language (JSON or XML)
Talk a simple standard language
ALPS = Application Level Profile Semantics
Be specific about your expectation and promise

6. You can use the command line…
curl "https://dspace7.4science.cloud/dspace-spring-rest/api"
But, there are better ways… using a REST client
Interacting with a REST API

7. • The Official REST Demo public instance (provided by 4Science)
– https://dspace7.4science.it/dspace-spring-rest/
• Navigate to the link above to explore
HAL Browser

9. Request + Headers

10. Response Headers
HTTP Status code

11. Response Body
RAW JSON Response
The HAL Browser will parse the key
elements:
_links
_embedded
Everything else

12. HAL Document

13. Response Properties

14. Links: All endpoints are available from the
Entry Point

15. Communities Endpoint Response
Communities
endpoint
Pagination
properties

16. Links - A generic approach to paginated
results

17. Embedded Community Properties

18. Embedded Community Links

19. On a COLLECTION Endpoint (“set of all” items, communities, etc.)
- POST Adds a new element to the collection
- GET Returns the first page of the resources in the collection
On a single RESOURCE Endpoint (specific item, collection, etc)
- GET Returns a single entity
- HEAD Returns whether the item resource is available
- PUT Replaces the state
- PATCH Similar to PUT but partially updating the resources state
- DELETE Deletes the resource exposed
Right use of the HTTP Verbs

20. ● uniform, consistent and self-documented behaviour
● full functional coverage, both for anonymous user and privileged
users
● stable, well documented and fully tested solution so that
integration will not easily break from one version to another
○ Test-Driven Development
○ Contract first approach
Reliable, stable and automatically tested
76% Test Coverage, mainly Integration Test
{ REST }

21. Supported Integration Scenarios

22. Reuse of the information
{ REST }
Embedding Javascript code
“Badge” in personal websites
List of departments and research
group publications
Complete backend integration
with search, browse, editing
capabilities

23. Data acquisition
{ REST }

24. Data acquisition
{ REST }
raw

25. Wide Institutional Process - Theses
Fill form to request Thesis
assignation in the Student
Management System
{ REST }
Student completes the
submission uploading the
Thesis in the repository
{ REST }
An external Anti-Plagiarism
system will analyze the
Thesis
Advisor approves
{ REST }
Graduation
recorded in the
Student
Management
System

26. 1. quick prototyping end users functionalities
a. notification services of pending tasks, unfinished submissions, …
b. reporting tools: usage, content and workflow statistics
2. extraction and external batch processing of the data in the
developer preferred programming language
3. data crawling and enrichment
More and more
… there are indeed no limits to the integrations that can be
implemented

27. «Alexa, ask DSpace demo for
the number of items»
Do you want to talks with DSpace?
«Alexa, ask DSpace demo to search
for molecular »
«Alexa, ask DSpace demo for information about John Smith»

29. Andrea Bollini, 4Science
andrea.bollini@4science.it
https://orcid.org/0000-0002-9029-1854