"links" used instead of "_links" when response contains a list of resource items

[jhoweaa]

I'm using Spring Boot 2.0 with Spring Boot HATEOAS 0.24.0.RELEASE and I'm seeing an inconsistency with the way my links are appearing when resources are rendered to JSON. If I return a single instance of Resource<Document> (where Document is a class we wrote), I will see something like this:

{
   "name": "some name",
   "format": "pdf",
   ...
   "_links": {
      "self" : {
          "href": "..."
      }
   }
}

This is from a method in my @RestController which is defined like this:

@RequestMapping(value = "/accessory", method = RequestMethod.GET, produces=MediaType.APPLICATION_JSON_VALUE)
public Resource<Document> getTestDocument() throws IOException, ReportServiceException {
    ...
}

however, if I return a list of Resource<Document> like this:

@RequestMapping(value = "/accessories", method = RequestMethod.GET, produces=MediaType.APPLICATION_JSON_VALUE)
public java.util.List<Resource<Document>> getAvailableDocuments() throws IOException, ReportServiceException {
  ...
}

I get results that look like this:

[
  {
    "name": "some name",
    "format": "pdf",
    "links": [
      {
        "rel": "self",
        "href": "..."
      }
      ...
  },
  ...
]

The only difference between the two is that in one case I'm returning a list of resources, and the other I'm just returning a single instance of the resource. Seems like a bug, but perhaps I'm just not setting something up correctly?

Thanks!

[gregturn]

The reason this happens is because List<Resource<Document>> is basically a List and Spring HATEOAS's HAL Serializers never engage, hence not producing a HAL document.

Your Spring MVC controller MUST return a ResourceSupport class, or one of its subtypes (Resource, Resources, PagedResources) for HAL serialization to work.

[gregturn]

Related to #629

[jhoweaa]

Thanks for the quick response. Is it the case that the proper HATEOAS form for a collection of documents is not to just generate the resource JSON and wrap it in an array? I modified my code to put the content into a Resources object and now I get the proper link formatting but I see this:

{
   "_embedded": {
        "documentList": [
              {
                  ... my document content as before ...
                  "_links":  {
                        "self": {
                            "href": "..."
    ...
}

The "_embedded" seems odd. Is the concept that the response is returning one object, which doesn't happen to have any content of it's own, but contains this embedded list of documents? Was wrapping the content in a Resources object the correct thing to do? The idea behind this particular REST request is the caller is expected to get back a collection of available documents, where each document contains some basic information about the document, along with links that can be used to access the document. It seems that the embedded adds an extra layer of indirection, but maybe that is the proper response?

Thanks for the help and information.

[gregturn]

1. If you are returning multiple items (like an aggregate root), then yes, wrapping it inside a Spring HATEOAS Resources object is correct. In fact, if each subelement is ALSO a tentative resource, then the proper type would be Resources<Resource<Document>>. That's because each entry has links, while the aggregate root itself has its own set of links.

2. You wish to spend a little team reading the HAL spec (http://stateless.co/hal_specification.html). You typically have either a single-item resource which is depicted with the bare fields + _links. Or you have the option to embed "other" related resources. Since you are embedded single-item resources into a collection, it fits the definition, and so we render that using _embedded.

3. If you have a RestTemplate registered in your application context in a client app, Spring Boot will register it with the HAL message converters, and it will properly parse _embedded when you consume for Resources<Resource<Document>>.

[jhoweaa]

Ok, I think this makes sense. I just found a couple examples of someone doing something similar and the results were similar to what I'm not getting so I'm comfortable with that. I'm also adding a 'self' link to the outer object so that I'll have both a '_links' with a self url pointing to the href which generated the content, along with the "_embedded" to deal with the list of document resources being returned.

[Kiolali]

The reason this happens is because List<Resource<Document>> is basically a List and Spring HATEOAS's HAL Serializers never engage, hence not producing a HAL document.

Your Spring MVC controller MUST return a ResourceSupport class, or one of its subtypes (Resource, Resources, PagedResources) for HAL serialization to work.

Thanks! I had the same problem. I'm using now ResponseEntity<CollectionModel<MyObject>> as the return value of my REST interface which produces "MediaType.APPLICATION_JSON_VALUE". In the Implementation I wrote:

CollectionModel<MyObject> model = CollectionModel.of(myObjects);
return new ResponseEntity<>(model, HttpStatus.OK);

(MyObject is derived from RepresentationModel<MyObject>)

Now I'm struggling with the string boot client. I tried:
CollectionModel<MyObject> myObjectsList= restTemplate.getForObject("http://localhost:8080/myobjectsAPI/myobjects", CollectionModel.class);

But there is an error which says "Could not find acceptable representation" (HTTP Status Code 406).
Retrieving a single myObject works: MyObject t = restTemplate.getForObject("http://localhost:8080/myobjectsAPI/myobjects/1", MyObject.class);

Any idea, what I'm doing wrong?

Thanks in advance!

Kiola

[Kiolali]

found my mistake.... My Server was producing application/json instead of application/hal+json