RESTful HATEOAS standards using Java based Katharsis
RESTful HATEOAS standards using Java based Katharsis
Keith D. Moore• Independent Software Consultant • KD Moore Consulting • http://www.kdmooreconsulting.com • [email protected] • @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