Getting started with DSpace 7 REST API

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?
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)

Why a new REST API?
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)
7.x
Bonus: better third-party
app integration!
https://github.com/DSpace/DSpace/tree/master/dspace-spring-rest

HATEOAS, HAL, & ALPS, oh my!
ALPS = Application Level Profile Semantics*
Describes the operations (actions) available for all REST endpoints.
(Machine-readable) metadata about how to interact with the API.
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.
RESULT: A standards-based, browseable, self-describing REST API
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.

Stateless (no session)
Specifications
• JSON web tokens (JWT)
• Cross-Origin Resource Sharing
(CORS) Headers
HTTP Resources
● URIs reference individual
resources or collections (of
resources)
● /items/{uuid} and /items
Formats: JSON* or XML
HTTP methods
GET (read), HEAD (read headers only)
POST (create)
PUT (replace), PATCH (partial update)
DELETE (remove)
OPTIONS (verify access, e.g. via CORS)
HTTP return codes
2xx (Success)
3xx (Redirect)
4xx (Client error)
5xx (Server error)
REST Terminology

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

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

Links: All endpoints are available
from the Entry Point

Links - A generic approach to
paginated results

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
Browser
• For this workshop, we will use
password authentication

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

Tabs and Collections help you
organize and re-use requests

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

Postman - Authenticating as a User

AuthN Status in Postman
(no AuthN token)

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
• GET
The second GET request will fail

Exercise 4: Modifying data with
Postman
Exercise 4 - Modifying data with
Postman

Managing Postman
• Postman allows you to use variables
and scripts to manage credentials
Tips on using postman

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

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)

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]

Implement DELETE (walkthrough)
1. ITs successful DELETE, failures due to
Authorization issues, DB constraints
[or18-ws3-it]
2. Check the implementation
[or18-ws3-fix]

Implement POST (walkthrough)
• How to test a create operation
• How to implement
[or18-ws4]

Implement Patch (walkthrough)
• Change the CanLogin flag
• Change the Password
[or18-ws5]

BONUS (discussion only)
• List/Create/Delete RegistrationToken
• How to transform a RegistrationToken
in an EPerson (text/uri-list)

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)
Join a Development Sprint!
Sign-up now!
https://tinyurl.com/dspace7sprints

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

Getting started with DSpace 7 REST API

More Related Content

What's hot

Similar to Getting started with DSpace 7 REST API

More from 4Science

Recently uploaded

In this document

Getting started with DSpace 7 REST API