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@example@.com).

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.

According to the [HAL draft RFC](https://tools.ietf.org/html/draft-kelly-json-hal-08#section-4) _`_embedded` contains embedded resources_ — Ilya Serbis, Apr 26 '18 at 16:30

score 46 · Accepted Answer · edited Oct 07 '22 at 01:41

46

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.

edited Oct 07 '22 at 01:41

Limon

194
1
11

answered Dec 11 '14 at 14:06

a better oliver

26,330
2
58
66

And who, or what, controls the writting of the `_embeded` node in the response payload ? – Stephane Aug 26 '18 at 17:17
2

`_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. – gregturn Nov 27 '18 at 03:40

Meaning and usage of "_embedded" in HATEOAS

1 Answers1

Linked