Javantura v4 - True RESTful Java Web Services with JSON API and Katharsis - Matija Dujmović

1. True RESTful Java Web
Services with JSON API
and Katharsis
MATIJA DUJMOVIĆ (NEOS)
ALEKSANDER RADOVAN (KING ICT)

2. What is REST?
Representational State Transfer
An architectural style defined by Roy Fielding in his doctoral dissertation, described by six
constraints
Resource-based
Uses representations
Protocol and media type agnostic

3. Richardson Maturity Model 1/3
A convenient model to help explain the specific properties of REST
Divided into four levels
Each higher level represents a more mature REST API with only the last level representing a true
REST API

4. Richardson Maturity Model 2/3

5. Richardson Maturity Model 3/3
Level 0: Swamp of POX
◦ Uses the HTTP protocol just as a transport layer through the HTTP POST method
◦ e.g. SOAP
Level 1: Resources
◦ Clearly distinguishes between resources but still uses only the HTTP POST method
◦ e.g. http://example.com/api/projects/123 represents a project resource with id 123
Level 2: HTTP verbs
◦ uses all HTTP verbs (GET for reading, POST for creating, PUT or PATCH for updating and DELETE for
deletion)
Level 3: Hypermedia
◦ Uses HATEOAS to deal with discovering the possibilities of your API towards the clients
◦ API-s that conform to this level are often called Hypermedia API-s

6. HATEOAS
Hypermedia As The Engine Of Application State
A constraint of the REST architectural style
By correctly using a hypermedia type in your REST API you are implicitly using HATEOAS
Let’s explain it by examining an API that uses a hypermedia type!

7. Hypermedia types 1/2
"Hypermedia Types are MIME media types that contain native hyper-linking semantics that
induce application flow. For example, HTML is a hypermedia type; XML is not."
Hypermedia APIs with HTML5 & Node, Mike Amundsen (2010)
"The WWW is fundamentally a distributed hypermedia application.”
Software Architecture: Foundations, Theory and Practice, Taylor, Medividovic, Dashofy (2010)
JSON isn’t a hypermedia type because it doesn’t have built-in support for hyperlinks
The REST architectural style is based on the architecture of the WWW.

8. Hypermedia types 2/2

9. JSON API
Created by Yehuda Katz, started drafting in 2013 and finalized in 2015
JSON API is the only media type that is currently a living standard
Actively used in the Ember.js JavaScript framework
Supported in Java with the Katharsis framework!

10. Example domain and API
The API endpoint is http://localhost:8080/api/ , only the changing part of the URI will be shown
in examples
The example domain is made of Project and Task objects
A Project object can have many Task objects
A Task object can have only one Project object

11. JSON and JSON API comparison

12. JSON API related URI

13. JSON API include relationship

14. JSON API using only one field

15. JSON API self URI

16. Katharsis
The Katharsis library adds an additional layer on top of RESTful endpoints to provide easy
HATEOAS support for Java by implementing the JSON API standard
Standard server-side framework integration
◦ Spring Boot
◦ Servlet
◦ JAX-RS (Java API for RESTful Web Services)
◦ Hibernate
Also offers a Java client for JSON API

17. Spring Boot and Katharsis 1/6
Project structure

18. Spring Boot and Katharsis 2/6
application.properties

19. Spring Boot and Katharsis 3/6
ExampleApplication.java

20. Spring Boot and Katharsis 4/6
Project.java , excluded getters, setters and constructors for readability

21. Spring Boot and Katharsis 5/6
ProjectRepository.java
@JsonApiFindOne -> GET projects/123
@JsonApiFindAll -> GET projects
@JsonApiFindAllWithIds -> GET projects/123,124
@JsonApiDelete -> DELETE projects/123
@JsonApiSave -> POST projects , PATCH projects/123

22. Spring Boot and Katharsis 6/6
ProjectToTaskRepository.java , implements the relationship endpoint
e.g.

23. Alternatives
http://projects.spring.io/spring-hateoas/ , hypermedia support with link building features
http://elide.io/ , quick JSON API endpoint development for JPA entities

24. More information
http://amundsen.com/hypermedia/ , Mike Amundsen’s page explaining hypermedia
http://katharsis.io/ , Katharsis project homepage
http://jsonapi.org/ , JSON API homepage
https://gtramontina.github.io/h-factors/ , visualization of available hypermedia and it’s features
Mike Amunden, Build Hypermedia APIs with HTML5 and Node, O’Reilly, 2010

25. Questions?

26. Thank you!