Meaning and usage of "_embedded" in HATEOAS

Question

I'm using Spring Data REST, which supports HATEOAS. I'm new to this paradigm.

In GET responses from my RESTful web service I often receive results inside a node named _embedded.

I'm wondering: what is _embedded node for? Is it part of REST specification? Or part of HATEOAS specification? Or is it specific for the Spring implementation of them?

This is an example of JSON result for GET http://localhost:8080/mywebservice/features:

{
   "_links":
   {
       "search": { "href": "http://localhost:8080/mywebservice/features/search" }
   },
   "_embedded":
   {
       "features":
       [
           {
               "feature": "GROUND",
               "name": "Terreno",
               "data_type": "String",
               "_links":
               {
                   "self"  : { "href": "http://localhost:8080/mywebservice/features/GROUND" },
                   "values": { "href": "http://localhost:8080/mywebservice/features/GROUND }
               }
           },

           ...

       ]
   }
}

I noticed that I almost always have _embedded node in the response: if I request a collection, but even if a request a single resource by a search (for instance with GET http://localhost:8080/mywebservice/persons/search/findByEmail?email=example@[email protected]).

I don't get _embedded node only if the request is for a specific resource, for instance when doing GET http://localhost:8080/mywebservice/features/GROUND.

Pardon

According to the HAL draft RFC _embedded contains embedded resources – Barbuto

Answer 1

There's neither a REST nor a HATEOAS specification. Both are only concepts, or architectural styles, if you will. _embedded is part of the HAL format.

It's intended to embed (sic!) resources where otherwise only their URIs would be returned. For example GET http://localhost:8080/mywebservice/features is supposed to only return a list of URIs, like http://localhost:8080/mywebservice/features/GROUND, and you would have to load every single Feature yourself if you needed it. By utilizing _embedded all Feature resources get embedded into the response so you don't have to load them separately.

Corell

And who, or what, controls the writting of the _embeded node in the response payload ? – Nuris

_embedded is defined by the HAL spec. Spring Data REST assembles a Resources object based on its knowledge of the applications repositories and domain model, and then delegate actual serialization to Spring HATEOAS, a library built to render various forms of spec-based hypermedia. – Fry