"Wrong Resource Type" When Collection Misses "_embedded"

[mathias-ewald]

Hi wrote a REST API with Spring HATEOAS and noticed that when there are not resources to return, the rendered JSON misses the _embedded property.

Code from the REST controller that produces the result:

Pageable pageable = PageRequest.of(pageIndex, pageSize);
Page<Article> page = articleRepo.findAll(pageable);
CollectionModel<ArticleV1Representation> colModel = articleAssembler.toCollectionModel(articleRepo.findAll(pageable));

PagedModel.PageMetadata md = new PagedModel.PageMetadata(
    page.getContent().size(),
    page.getNumber(),
    page.getTotalElements(),
    page.getTotalPages());

PagedModel<ArticleV1Representation> model = PagedModel.of(colModel.getContent(), md);
model.add(linkTo(methodOn(ArticleV1RootController.class).getAll(0, pageSize)).withRel("first"));

The result produced when there are no entities in the repository:

{
  "_links" : {
    "first" : {
      "href" : "http://localhost:8081/articles?page=0&size=20"
    },
    "self" : {
      "href" : "http://localhost:8081/articles?page=0&size=20"
    },
    "last" : {
      "href" : "http://localhost:8081/articles?page=0&size=20"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

The UI code to fetch the data:

this.resourceService.getPage(Article, opts)
  .pipe(delay(500))
  .subscribe((page: PagedResourceCollection<Article>) => {
  ...
});

Error produced in the UI:

Since the HAL specification (https://datatracker.ietf.org/doc/html/draft-kelly-json-hal#section-4.1.2) tells that _embedded is optional, I am opening an issues here.

[lagoshny]

Hi @mathias-ewald !

In this case, I relied on Spring Data REST behavior for empty collections.
It means that if you have an empty collection, then Spring Data Rest puts an empty object as _embedded: { your_resource_name: [] } property.

This behavior allows simpler to determine what is Resource type: Collection, Page, or simple Resource.

As I understand you use Spring HATEOAS, you can try to repeat the same behavior as Spring Data REST using some part of code:

HalModelBuilder.emptyHalModel()
  .embed(Collections.emptyList(), Order.class);
  // or
  .embed(Collections.emptyList(), LinkRelation.of("orders"));

Then it will be rendered the next JSON for an empty collection:

{
  "_embedded" : {
    "orders" : []
  }
}

See more in Spring HATEOAS docs.

[lagoshny]

If you can not make an empty _embedded property for an empty collection. Write about it, I will think how to make _embedded property as optional.

[mathias-ewald]

Hi @lagoshny,

think it'll be difficult to tell the backend team to do something the specification does not require to be compatible with the frontend library I am using.

Is there a way to catch and handle that error somehow?

cheers,
Mathias

[lagoshny]

@mathias-ewald
I think it is good design to write predictable API and even if specification says that _embedded is optional it is not saying that it is good in some case to put _embedded in another not. And to know about it, you need to read specification.

To help you, I added new config option that allow resource collections without _embedded.

Add option in lib config (see more in docs):

halFormat: {
   collections: {
      embeddedOptional: true
    }
}

This features available since 3.3.0 version and 2.6.0 lib versions.