RESTful HATEOAS standards using Java based Katharsis

Keith D. Moore• Independent Software Consultant • KD Moore Consulting • http://www.kdmooreconsulting.com • keith@kdmooreconsulting.com • @keithdmoore94 • in/keithdmoore94

What is a RESTful API?

An application program interface (API) that uses HTTP methods like GET, POST, PUT, PATCH, OPTIONS and DELETE to make requests and receive responses.

HTTP Methods for REST• GET - this is a read method (get all/get one)

• POST - this is a create method

• PUT - this is an update method (usually a full replacement)

• PATCH - this is an update method (usually partial)

• OPTIONS - typically used for preflight requests or metadata

• DELETE - this a delete method

HATEOAS• (Hypermedia as the Engine of Application State) is a constraint

of the REST application architecture. A hypermedia-driven site provides information to navigate the site's REST interfaces dynamically by including hypermedia links with the responses.

• Allows a client to navigate a set of resources with very little documentation.

• Allows for resource urls to change without impacting the client.

• Essentially provides the ability to create a self-describing API

Parkinson's law of triviality is C. Northcote Parkinson's 1957 argument that members of an organization give disproportionate weight to trivial issues. He observed that a committee whose job was to approve the plans for a nuclear power plant spent the majority of its time on discussions about relatively minor but easy-to-grasp issues, such as what materials to use for the staff bike-shed, while neglecting the proposed design of the plant itself, which is far more important but also a far more difficult and complex task.

The Bikeshed moment• How are the requests/responses going to be formatted?

• Are we going to use a PATCH method for full and partial updates?

• What is the format for a pagination or sorting request?

• How will requests be structured that act on resource relationships?

• How will error responses be formatted?

JSON API to the rescue• JSON API is a specification for how a client should request that resources be

fetched or modified, and how a server should respond to those requests.

• http://jsonapi.org (there really is a specification for it)

• Even has its own media type: application/vnd.api+json

• Lots of MUST, MUST NOT, SHOULD, MAY, etc.

• There are still some decisions to be made but this gives you a framework to make some of the more fine grained decisions.

• Several implementations in a variety of languages. Both client-side and server-side.

REST URI’s•GET /api/tasks: returns all tasks •GET /api/tasks/1: returns the task with ID 1 •POST /api/tasks: creates a task with the data sent in

the body •PATCH /api/tasks/1: updates the task with ID 1 with

the data sent in the body (only send what you want to update)

•DELETE /api/tasks/1: delete the task with ID 1 •OPTIONS /api/tasks: metadata about the member

resource

Sample Response{ "data": { "type": "articles", "id": "1", "attributes": { “title”: “Having fun with JSON”, “description”: “Explore the fun you can have with JSON.” }, "relationships": { "author": { "links": { "self": "/articles/1/relationships/author", "related": “/articles/1/author" } } } } }

atharsis• a Greek word meaning "cleansing" or “purging” • Elegant and powerful HATEOAS framework for Java based on the

JSON API standard • Uses ResourceRepository and ResourceRelationshipRepository • Annotation based or interface based • Modular

• Core • Spring • JAX-RS • Servlet • Vertx • Examples

• Very few dependencies

Let’s look at Katharsis in Action

Filter/Sort/Group/Pagination• GET /api/tasks?filter[tasks][name]=Make%20Coffee • GET /api/tasks?sort[tasks][name]=asc • GET /api/tasks?group[tasks]=name • GET /api/tasks?include[tasks]=project • GET /api/tasks?page[offset]=0&page[limit]=10

Pagination using Links "links": { "self": “http://example.com/articles/22“, "first": “http://example.com/articles?page[offset]=0” "prev": “http://example.com/articles?page[offset]=1” "next": "http://example.com/articles?page[offset]=3", "last": "http://example.com/articles?page[offset]=10" }

References and Links• http://jsonapi.org

• https://en.wikipedia.org/wiki/HATEOAS

• http://katharsis.io

• https://en.wikipedia.org/wiki/Law_of_triviality