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.

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.