Getting Started with

DSpace 7 REST API

Andrea Bollini, 4Science

Terry Brady, Georgetown
Tim Donohue, DuraSpace
 Workshop Schedule

❖ Why a new REST API?

❖ Interacting with REST API
❖ (Morning Tea 10:30-11:00)
❖ Design Principles of REST API
❖ Developing the REST API
Version 7.0 goals
★ Single, Angular UI (new)
★ Fully-featured REST API (new)
★ Configurable Entities (new)
★ Align w/ NGR recommendations
★ Existing, core Java backend
(DB, Solr, Assetstore)
Current Status
❏ Enhanced backend (object store, caching, speed improvements)
❏ Browse (Homepage, Community, Collection, Item pages)
❏ Search
❏ Authentication and Authorization
❏ Submission
❏ Approval Workflows
❏ Content Management (Create/Edit/Delete tasks)
❏ Administration
❏ Statistics
❏ Configurable Entities support
Development Planning Spreadsheet
Why a new REST API?
Why a new REST API?
Covers only a Not based on current
subset of DSpace REST best practices
functionality 4.x - 6.x or standards
No search
No submit / workflows
Limited admin operations
Limited write / delete
(4.x was read only)
Handcrafted in Jersey,
while most DSpace code uses
Spring technologies
 Why a new REST API?
All features MUST Defined REST Contract.
be in REST API HATEOAS, ALPS,
(for Angular UI) 7.x HAL format

Bonus: better third-party

app integration!

Built using Spring technologies

(Spring Boot, MVC, HATEOAS)

https://github.com/DSpace/DSpace/tree/master/dspace-spring-rest
HATEOAS, HAL, & ALPS, oh my!
HATEOAS = Hypertext As The Engine Of Application State
In each response, include “links” to available next requests.
Results in better decoupling, as API is self-describing.

HAL Format = Hypertext Application Language (JSON or XML)

A standard format for making REST APIs browseable
(think HTML for machines). Open source HAL Browser available.

ALPS = Application Level Profile Semantics*

Describes the operations (actions) available for all REST endpoints.
(Machine-readable) metadata about how to interact with the API.

RESULT: A standards-based, browseable, self-describing REST API

 REST Terminology
Stateless (no session) HTTP methods
GET (read), HEAD (read headers only)
POST (create)
Specifications
PUT (replace), PATCH (partial update)
• JSON web tokens (JWT) DELETE (remove)
• Cross-Origin Resource Sharing (
OPTIONS (verify access, e.g. via CORS)
CORS) Headers

HTTP Resources HTTP return codes

● URIs reference individual 2xx (Success)
resources or collections (of 3xx (Redirect)
resources) 4xx (Client error)
● /items/{uuid} and /items
5xx (Server error)

Formats: JSON* or XML

Interacting with the
REST API
(HAL browser, Postman, command line?)
 Interacting with a REST API

You can use the command line…

curl "https://dspace7.4science.it/terry/api/core/collections"

But, there are better ways… using a

REST client
 Goals for this section

• Understand the endpoints that are

available
• Learn how to call these endpoints
– As an anonymous user
– As an authenticated user
• Appreciate the self-describing nature of
the DSpace REST design
 We will look at 2 tools

• HAL Browser
• Postman

The REST API currently supports very

limited modification actions
(create/update/delete). More support will
be added in the future.
 HAL Browser

• Development public instance (provided

by 4science)
– https://dspace7.4science.it/dspace-spring-rest
/
• Workshop Link
– https://dspace7.4science.it/terry
• Navigate to the link above to explore
HAL Browsing - Example
 Response Object Components

• Response Properties
– Often pagination details
• Links
– What you can do next
• Embedded Resources
– List of objects which may contain
• Properties
• Links
 Open the API Landing Page

• Open the Entry Point

– https://dspace7.4science.it/terry
• Request (in HAL Browser)
– /api
Request + Headers
Response Properties
Links: All endpoints are available
from the Entry Point
Response Headers
Response Body
Example: Items Endpoint
Items Response
Links - A generic approach to
paginated results
Embedded Item Properties
Embedded Item Links
Exercise 1: Explore HAL Browser

Exercise 1 - Exploring Endpoints in HAL

Browser

Short Link To Exercises

http://bit.ly/dspace7-rest
 The REST contract

• https://github.com/DSpace/Rest7Contract
– Explore the list of endpoints
• Implemented
• Unimplemented
• Under discussion
– Use GitHub pull requests to suggest
changes
The future of REST API Documentation

PR#1915
 REST Authentication

• The existing DSpace authentication

methods will be supported
• The REST API returns an authentication
token
• This token is passed to subsequent
REST requests as a header
 Why Authenticate?

• View restricted items/bitstreams

• Create/Update/Delete Objects
– Submit items
• Perform admin operations
• View restricted metadata (provenance)
• Note: most of these actions are not yet
supported in DSpace REST
A subset of these operations are
available in HAL
Exercise 2: Authenticating in HAL

Exercise 2 - Authentication in HAL Brow

ser
• For this workshop, we will use
password authentication

http://bit.ly/dspace7-rest
 Limitations of HAL Authn

• Credentials only passed for GET

operations
• File uploads not supported
Postman - A development client for
REST API’s
https://www.getpostman.com/apps
Postman - A tool for sending REST
requests
• Postman is a tool for interacting with
various REST services
– Even ones without a HAL Browser
• Using a web browser, it is difficult to
construct complex requests
Postman
Tabs and Collections help you
organize and re-use requests
Request Area
Parameters and Headers
Response Panel
Response Headers
 Browsing with Postman

• View all items

– /api/core/items
• Change page size
– /api/core/items?size=5
• Change starting page
– /api/core/items?size=5&page=2
Exercise 3: Browsing with Postman

Exercise 3 - Browsing with Postman

http://bit.ly/dspace7-rest
Postman - Authenticating as a User
AuthN Status in Postman
(no AuthN token)
Authenticating in Postman
AuthN Status in Postman
(passing Bearer token)
 Let’s Attempt to change data

• The current REST API allows a user to

start a submission
• POST
– /api/submission/workspaceitems
– Body: {}
• The response will return an object with
an id
 Retrieving the Item that was
created
• GET
– /api/submission/workspaceitems/[id]
• DELETE
– /api/submission/workspaceitems/[id]
• GET
– /api/submission/workspaceitems/[id]
The second GET request will fail
Exercise 4: Modifying data with
Postman
Exercise 4 - Modifying data with Postma
n

http://bit.ly/dspace7-rest
 Managing Postman

• Postman allows you to use variables

and scripts to manage credentials

Tips on using postman

Design Principles
 REST Terminology
Stateless (no session) HTTP methods
GET (read), HEAD (read headers only)
POST (create)
Specifications
PUT (replace), PATCH (partial update)
• JSON web tokens (JWT) DELETE (remove)
• Cross-Origin Resource Sharing (
OPTIONS (verify access, e.g. via CORS)
CORS) Headers

HTTP Resources HTTP return codes

● URIs reference individual 2xx (Success)
resources or collections (of 3xx (Redirect)
resources) 4xx (Client error)
● /items/{uuid} and /items
5xx (Server error)

Formats: JSON* or XML

Hypermedia as the Engine of Application
State - HATEAOS

HAL Format ALPS

Links are expressed in a Available methods, semantics of
standard/well-known way in the request and response objects
json response (it is also suitable for discoverable in a standard way
xml but DSpace7 will focus only on (/profile) and expressed in multiple
JSON) standards format (Alps JSON, JSON
Schema, XML, etc)
→ enable the interactive navigation → enable to expose only available
methods (i.e. GET on
→ abstract routing (URL can change resourcepolicies is disallowed)
without break the client)
→ document in a machine-readable
→ support documentation way the request and response
semantics
HAL Document
ALPS will enable...
 REST Maturity level

Image from: https://martinfowler.com/articles/richardsonMaturityModel.html

 Spring technologies

Spring Bootstrap: pre-configured managed

Spring platform
Spring MVC: Front Controller, data binding,
error handling
Spring REST: MVC extension to easily
support Content-Negotiation, Response in
JSON format
 Spring technologies

Spring HATEOAS: library to deal with HAL

Document (Resources, Resource, Links, Curie)
Spring Data REST: only for inspiration
(consistent design choices, HTTP error
handling, support classes, etc.)
 Spring technologies

Spring Data REST Hal Browser: WebJar of

the HAL browser customized to work at best
with Spring Data REST
Spring REST Docs: Self contained
documentation with snippets from Integration
Tests
 Pagination
https://github.com/DSpace/Rest7Contract#pagination

Resource Collections are always paginated

→ pagination information are returned in a
consistent way across all the endpoints
→ pagination parameters are expected in the
same form in all the endpoints
→ common JAVA API to deal with page jump
and offset
 Search Methods
https://goo.gl/NSju3q

Collection endpoints that allowing

filtering, search or precise lookup of
resources MUST provide a search link
listing all the available methods
 Right use of the HTTP Verbs:
collection
- POST Adds a new element to the
collection.

- GET Returns the first page of the

resources in the collection
 Right use of the HTTP Verbs:
element
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.
 How to deal with PATCH

JSON Patch specification RFC6902

Express change to a JSON Object in JSON
Array of Operations executed in an atomic
transaction
Each successful Patch operation will return a
HTTP 200 CODE with the new state of the
patched resource as body similar to what is
returned for a GET request.
 How to deal with PATCH

ADD / REMOVE / REPLACE / MOVE

[
{ "op": "test", "path": "/a/b/c", "value": "foo" },
{ "op": "remove", "path": "/a/b/c" },
{ "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] },
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy", "from": "/a/b/d", "path": "/a/b/e" }
]

TEST & COPY (no plan to support them)

 PATCH (More examples: https://goo.gl/G84oRQ)
[{
"op": "add",
"path": "/sections/traditionalpageone/dc.contributor.author/-",
"value": {"value": "Another, Author"}
}]
 HTTP status codes - 2xx, 3xx

200 Ok - Normal success state

201 Created - Returned when a resource is created
204 No content - Returned when the operation succeed but no
content is available (i.e. hit the logo endpoint of a community
without logo
206 Partial Content - DSpace 7 provides range support for
bitstream download allowing streaming

302 Found - the PID endpoint redirect to the target resource

 HTTP status codes - 4xx

400 Bad Request - if the request is invalid (not a json, etc.)

401 Unauthorized - if the request require a logged-in user
403 Forbidden - if the requester doesn't have enough privilege
to execute the request
404 Not found - if the requested resource doesn't exists
405 Method Not Allowed - if the requested verb is not
supported for the resource
422 Unprocessable Entity - if the request is semantically
invalid (i.e. attempt to add undefined metadata, deposit an
invalid workspace)
Developing the
REST API
 Code used in the workshop

https://github.com/4Science/DSpace

Branch: or2018-workshop (final result)

| tags will help to move step by step
\ or2018-workshop-start
How URL are translated to JAVA
code
Where is my web.xml?

It is a spring boot application with web

support (MVC)
Controller → are the “new” Servlet
@RestController
What about the lovable spring xml files?

sorry now we use annotations :)

Component scanning enabled on

repository, converter, utils packages
@Component
@Service
 Goal: Enhance the EPerson
endpoint
• List EPersons (already exists)
• Get EPerson (already exists)

Walkthrough the implementation and the

Integration Tests
[tag: or2018-workshop-start]
 Rest Model Class

• POJO used as DTO between the REST

layer and the services.
• Clean and stable version of our data
model
• The converter class transcode the
DSpace-API objects in REST objects
 Repository Class

• It is defined in the
Repository design pattern
• It implements the Data Access Layer in
DDD
• Close to the domain model, abstracting
access to a collection
 Resource Class

• Wrap the Domain Class inside an HAL

document
• Provide supports to add links
• Manage embedded objects
 Integration Test

Builder and Matcher helper classes to keep code

compact & cleanup the test database between
runs
One or more test for each repository methods
- Separate test for different scenarios
(exception, limit case, normal case)
- Multiple calls in the same test to cross check
the intent changes
 Add security check

Learn how to authenticate an user in

the Integration Test [or18-ws1-it]

Secure the main eperson endpoint (only

administrators can access) [or18-ws1-
fix]
 Enhancing EPerson endpoint

Implement Search by email, by name

(walkthrough)
1. Write Integration Tests in advance [or18-
ws2-it]
2. Implement the endpoint, run the test [or18-
ws2-search / or18-ws2-search2]
3. Interact using the HAL browser [or18-ws2-
fix]
 Enhancing EPerson endpoint

Implement DELETE (walkthrough)

1. ITs successful DELETE, failures due to
Authorization issues, DB constraints
[or18-ws3-it]
2. Check the implementation [or18-ws3-
fix]
 Enhancing EPerson endpoint

Implement POST (walkthrough)

• How to test a create operation
• How to implement

[or18-ws4]
 Enhancing EPerson endpoint

Implement Patch (walkthrough)

• Change the CanLogin flag
• Change the Password

[or18-ws5]
 Enhancing EPerson endpoint

BONUS (discussion only)

• List/Create/Delete RegistrationToken
• How to transform a RegistrationToken
in an EPerson (text/uri-list)
Join a Development Sprint!
DSpace 7 will arrive more quickly with more help!

❏ 1st DSpace 7 Community Sprint: May 7 - 18

❏ 14 pull requests, 8 contributors (2 first time)
❏ 2nd DSpace 7 Community Sprint: July 9 - 20
No availability requirements! Choose your own tickets/tasks!
No DSpace 7 experience necessary! (Coaches available)

Sign-up now!
https://tinyurl.com/dspace7sprints
 Questions?

Slides available at
https://tinyurl.com/or2018-dspace-rest
Sl