True RESTful Java Web Services with JSON API and KatharsisMATIJA DUJMOVIĆ (NEOS)

ALEKSANDER RADOVAN (KING ICT)

What is REST?Representational State Transfer

An architectural style defined by Roy Fielding in his doctoral dissertation, described by sixconstraints

Resource-based

Uses representations

Protocol and media type agnostic

Richardson Maturity Model 1/3A 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 trueREST API

Richardson Maturity Model 2/3

Richardson Maturity Model 3/3Level 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

HATEOASHypermedia 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!

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.

Hypermedia types 2/2

JSON APICreated 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!

Example domain and APIThe API endpoint is http://localhost:8080/api/ , only the changing part of the URI will be shownin 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

JSON and JSON API comparison

JSON API related URI

JSON API include relationship

JSON API using only one field

JSON API self URI

KatharsisThe Katharsis library adds an additional layer on top of RESTful endpoints to provide easyHATEOAS 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

Spring Boot and Katharsis 1/6Project structure

Spring Boot and Katharsis 2/6application.properties

Spring Boot and Katharsis 3/6ExampleApplication.java

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

Spring Boot and Katharsis 5/6ProjectRepository.java

@JsonApiFindOne -> GET projects/123

@JsonApiFindAll -> GET projects

@JsonApiFindAllWithIds -> GET projects/123,124

@JsonApiDelete -> DELETE projects/123

@JsonApiSave -> POST projects , PATCH projects/123

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

e.g.

Alternativeshttp://projects.spring.io/spring-hateoas/ , hypermedia support with link building features

http://elide.io/ , quick JSON API endpoint development for JPA entities

More informationhttp://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

Questions?

Thank you!