If you ever want to start a controversy at the beginning of a SPA or mobile project, just start talking about the way the JSON responses should be formatted and how the requests will be sent. Don’t be that guy! There are definitely much more important things to discuss like, for example, what the application is going to do. You can end the bike shedding by following the JSON API spec (http://jsonapi.org). Yes, there really is a specification for it. I will discuss how you can easily implement this along with providing HATEOAS support using the Java based Katharsis (http://katharsis.io) library. I will demonstrate how this can be done by incorporating it into a Spring Boot application.

1. RESTful HATEOAS
standards using
Java based
Katharsis

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

3. 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.

4. 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

5. 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

6. 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.

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

8. 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.

9. 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

10. 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"
}
}
}
}
}

11. 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

12. Let’s look at Katharsis in Action

13. 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

14. 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"
}

15. References and Links
• http://jsonapi.org
• https://en.wikipedia.org/wiki/HATEOAS
• http://katharsis.io
• https://en.wikipedia.org/wiki/Law_of_triviality