otto-de / edison-hal

A library to parse and render application/hal+json documents in Java

Edison HAL

Library to produce and consume application/hal+json representations of REST resources using Jackson.

1. Documentation

• JavaDoc
• User Guide explains how to use edison-hal in your projects.
• Change Log for latest changes.

2. About

At otto.de, microservices should only communicate via REST APIs with other microservices. HAL is a nice format to implement the HATEOAS part of REST. Edison-HAL is a library to make it easy to produce and consume HAL representations for your REST APIs.

Currently, there are only a couple of libraries supporting HAL and even less that support the full media type including all link properties, curies (compact URIs) and embedded resources.

Spring HATEOAS, for example, is lacking many link properties, such as title, name, type and others.

3. Features

Creating HAL representations:

• Links with all specified attributes like rel, href, profile, type, name, title, etc. pp.
• Embedded resources, even deeply nested
• Curies in links and embedded resources
• Generation of HAL representations using Jackson annotations

Parsing HAL representations:

• Mapping application/hal+json to Java classes using Jackson. This also works for deeply nested embedded items.
• Simple domain model to access links, embedded resources etc.
• Curies are automatically resolved: Given a curi with name=ex and href=http://example.com/rels/{rel}, links and embedded items can be access either in curied format ex:foo, or expanded format http://exampl.com/rels/foo

Traversion of HAL representations:

• Simple client-side navigation through linked and embedded REST resources using Traverson API
• Embedded resources are transparantly used, if present.
• Curies are resolved transparantly, too. Clients of the Traverson API do not need to know anything about curies or embedded resources.

edison-hal's Issues

Represensentations with single embedded item for a link-relation type

A single embedded item for a rel can not be parsed:
{
'_embedded' : {
'foo' : {'will':'not work'}
}
}

HalParser: support for multiple EmbeddedTypeInfos to specify type of embedded items

Traverson should support multiple embedded type-infos, just like HalRepresentations

Traverson is ignoring embedded items

Traverson should not follow links if the linked items are embedded. At least using relative links and maybe also with curies links, this is currently not the case.

Allow customization of the Jackson ObjectMapper used in HalParser

Without this, it's impossible to add modules to make client-side deserialization match the server-side serialization configuration.

Do not catch / hide Exceptions thrown while traversing resources

In 1.0.0, Exceptions are caught by the Traverson. Clients have to check for Exceptions using Traverson.getLastError(), which is not too obvious.
Beginning with 2.0.0, the Traverson is exposing the Exceptions (IOException) in the API, so clients have a better chance to add appropriate error handling.

Next page computed wrong in zero based paging

In NumberedPaging the flag hasMore is computed wrong for zero based paging. Therefore the next page link is rendered, even when there are no more pages.

Resolving relative URLs in Links

Provide support for resolving relative HREFs in links so the client does not have to worry about relative/absolute links in HAL representations.

Traverson: Specify Type of embedded items

Traverson.getResource: gets a resource as HalRepresentation
Traverson:getResourceAs(type): gets a resource as
Missing: specification of the type of embedded items.

Embedding items in embedded resources

While it is possible to embed items in embedded resources, CURIs in deeply embedded items are not handled properly. This is possibly leading to unresolvable curied links.

New release with updated dependecies to resolve CVEs

Hey @gsteinacker,
I saw that you got a bot to bump dependencies ( which fixed a cve in my project), so i was wondering if you could publish a new release of this lib.

Thank you for your attention to this matter. Looking forward to the updated release!

Add more / refactor existing examples

Add Traverson.follow() methods to bypass embedded resources.

In application/hal+json, linked resources may optionally be embedded into a resource. Right now, the Traverson is always using embedded resources, if present. While this is helpful in most situations, clients may want to bypass the embedded items and resolve links instead. For example, server might embed only a subset of a resource, while the client might need to get the full representation.

"_embedded" (single) resource object not supported?

Is it correct - when rendering HalRepresentation - that is not supported to have a single resource object in _embedded?

As per the spec:

The reserved "_embedded" property is OPTIONAL

It is an object whose property names are link relation types (as
defined by [RFC5988]) and values are either a Resource Object or an
array of Resource Objects.

edison-hal seems to only allow to set a list of resources in the _embedded property like:

protected HalRepresentation withEmbedded(final String rel, final List<? extends HalRepresentation> embeddedItems)

In some cases an explicit single resource is desired instead of an array.

EmbeddedTypeInfos for single embedded item is not resolved

_embedded may contain single items instead of an array of items. In case of single items, type information is not resolved.

Accessing custom JSON attributes

It is currently required to sub-class HalRepresentation, if custom JSON attributes are required.
Generating or at least reading additional attributes using a generic API would be nice. This way, it would be possible to implement Tools similar to the HAL Browser without having to know about such attributes.

Question: Use already existing domain-model?

I tried to understand edison. For me it seems that I need to write my own HalRepresentation. But I already have a domain-model. Is it possible to use this and add some specific mapping or do I need to reimplement (define Halpresentations with all properties) my domain model.

Globally outputting null values of hal represenations

HalRepresentation has a @JsonInclude(NON_NULL) annotation which causes to not include null properties of resources.

It would be nice to switch off this behaviour globally.

That said I can imagine that e.g. _embedded is not desired to be outputted when null.
Maybe it's better to move the @JsonInclude(NON_NULL) to particular fields of HalRepresentation?

Creation of Multiple Links Representation should be based on RelationType and not on number of elements of that type

Due to

edison-hal/src/main/java/de/otto/edison/hal/Links.java

Line 480 in 945c37c

if (links.size() > 1 || rel.equals("curies")) {

it is currently not possible to have a link relation type (other than curries) that should be represented as a multiple, if there are less than two elements of that relation type.

Example:
The custom link relation type "myType" should allow multiples.

HalRepresentation.withLinks(
   Link.link("myRelationType", "http://www.example.com/myResource/1"),
   Link.link("myRelationType", "http://www.example.com/myResource/1"))
/* Will produce:
...
"_links": {
  "myRelationType": [
    {
      "href":"http://www.example.com/myResource/1"
    },
    {
      "href":"http://www.example.com/myResource/2"
    }
  ]
}
...
*/

HalRepresentation.withLinks(
    Link.link("myRelationType", "http://www.example.com/myResource/1")) 
/* Will produce:
...
"_links": {
  "myRelationType": {
      "href":"http://www.example.com/myResource/1"
    }
}
...
Should produce: 

...
"_links": {
  "myRelationType": [
    {
      "href":"http://www.example.com/myResource/1"
    }
  ]
}
...
*/

remove duplicate curis from embedded resources

Hi,

I have an idea for improvment and I would like to know what you think.

I have multiple HalRepresentation which have rels which use curis. Representation A would like to embed representation B, both use rels which can use the same curi.

My HAL representation factory of B always includes a curi link. When I now serialize an Repr. A, the curi will be duplicated in the JSON.

At the moment embedded representations use the relRegistry of the parent, it would be nice to remove duplicated curis at the same time.

Support paginate() and paginateAs() with custom link-relation type

Currently, only 'next' and 'prev' is supported when paginating resources. Another set of methods should be provided, so other / custom rels could also be used to iterate over pages of items.

Move configuration of link-relation types to LinkRelations

Currently, links are rendered as an array if there are multiple links for a link-relation type.
Because it should be specified, whether or not a link-relation type is an array of links, or not, LinkRelations can be used.

Paging of Items

The Traverson already makes it easy to iterate over items in a page. However, iterating over multiple /all pages and all items per page is not supported.
The Traverson should be refactored to support this.

Add support for traversing everything up to last hop

I've come across a new use case where I'd like Traverson to navigate the API but then delegate the last request to something else (in my case, Spring's MockMvc for assertions).
Currently, the only way to do that is by using something like

traverson.follow("item")
    .follow("parent")
    .follow("item")
// or one of the similar methods
    .getResource();
mockMvc.perform(put(traversion.currentContextUrl().toUri()))
    .andExpect(...);

Although this mostly does the right thing, it issues an unnecessary GET request for the last hop (which might fail for several reasons).

Would it be possible to add a traversalUrl() method (or something with a better name) that supports things like

traverson.follow("item")
    .follow("parent")
    .follow("item");
mockMvc.perform(put(traverson.traversalUrl().toUri()))
    .andExpect(...);

Deserialization of json string into HalRepresentation and subsequent serialization are not symmetrical

When I deserialize a json string into a HalRepresentation, I can observe that all attributes are deserialized correctly into the instances attributes map. However, those very same attributes are not serialized when subsequently serializing the instance to json string.

My use case is a proxy service which does some limited interpretation of HalRepresentations, before passing them on.

Configuration of array rels should be used to render _embedded items

Add Logging to support analysis of problems