Removing _embedded from a collection of REST resources

Question

Maybe this goes against REST/HAL principles but I thought that if I was viewing a list of items they should not be contained in an _embedded tag. Below is the details returned when I navigate to /characters in my spring boot application.

I had expected _embedded to not be present for the characterDescriptions since they are the main focus of the page, is it possible to achieve this? Should I try to achieve this or would _embedded be the norm here?

On a related note when I navigate to a particular resource using the link ( like characters/1 for instance) should I be linking back to the /characters parent page or is it acceptable to only contain a self-link at these kinds of endpoints (I will be eventually linking to the user here but this is a general question about REST endpoints )

The controller method that returns this JSON is below the JSON

{
    "_embedded": {
        "characterDescriptions": [
            {
                "characterName": "Adrak",
                "playerName": "Liam",
                "userName": "liam",
                "_links": {
                    "self": {
                        "href": "http://localhost:8080/characters/1"
                    }
                }
            },
            {
                "characterName": "Thorny",
                "playerName": "Aedo",
                "userName": "aedo",
                "_links": {
                    "self": {
                        "href": "http://localhost:8080/characters/2"
                    }
                }
            },
            {
                "characterName": "Anin",
                "playerName": "Saoirse",
                "userName": "saoirse",
                "_links": {
                    "self": {
                        "href": "http://localhost:8080/characters/3"
                    }
                }
            }
        ]
    },
    "_links": {
        "self": {
            "href": "http://localhost:8080/characters"
        }
    }
}

Here's the relevant method

    @GetMapping
    public ResponseEntity<Resources<Resource<CharacterDescription>>> getAllCharacterDescriptions( ) {

        List <Resource<CharacterDescription>> characters = repository.findAll()
                .stream().map( character -> {
                    Link characterLink = linkTo(methodOn(CharacterDescriptionController.class)
                            .getCharacterDescription(character.getCharacterId()))
                            .withSelfRel();
                    return new Resource<>(character, characterLink);
                }).collect(Collectors.toList());

        Link allCharacterLink = linkTo(methodOn(CharacterDescriptionController.class)
                                        .getAllCharacterDescriptions(auth))
                                        .withSelfRel();

        Resources<Resource<CharacterDescription>> resources = new Resources<>(characters, allCharacterLink);
        return ResponseEntity.ok(resources);
    }

You could try to annotate the embedded resources with [@JsonUnwrapped](https://fasterxml.github.io/jackson-annotations/javadoc/2.0.0/com/fasterxml/jackson/annotation/JsonUnwrapped.html) similar to [an example](https://github.com/opencredo/spring-hateoas-sample/blob/master/src/main/java/com/opencredo/demo/hateoas/api/resources/ResourceWithEmbeddeds.java#L11) which defines its own embedded resource support class — Roman Vottner, May 23 '18 at 14:53
Here page is considered as a resource itself, that is why `characterDescriptions` are under `_embeded` — ahmedjaad, Sep 22 '18 at 10:22

score 0 · Answer 1 · edited Oct 07 '21 at 07:27

According to the HAL spec you can either render a single resource, with its content and set of links, or you can render an aggregate resource, which has room for multiple resources-within-this-resource.

In your domain model, you clearly show multiple documents, each with a distinct self URI (/characters/1, /characters/2, etc.), hence, you aren't serving up a single item resource, but instead an aggregate root.

If you read the HAL spec, you'll find this definition underneath _embedded:

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.

In fact, looking for the word array in the HAL spec, only leads you to section quoted above, and the _links section.

Hence, _embedded is the proper place to render an array of resources in HAL.

Removing _embedded from a collection of REST resources

1 Answers1