api - How to correctly use HAL (Hypermedia Application Language) _embedded? -

i building rest api exposes information online courses users. here general structure of course:

course > units > lessons > activities

i'm trying make json response structure hal compliant, i'm unsure if i'm doing correctly.

which of following correct:

{   “kind”: “clms#course”,   “id”: long,   “course-name”: string,   “course-icon”: string,   “product-name”: string,   “product-icon”: string,   “_links”: {     “self”: {“href” : string},      “unitlist”: {“href” : string} // link list of units course.   } } 

or link list of units _embedded resource?

{       “kind”: “clms#course”,       “id”: long,       “course-name”: string,       “course-icon”: string,       “product-name”: string,       “product-icon”: string,       “_links”: {         “self”: {“href” : string},        }       "_embedded": {         “unitlist”: {“href” : string} // link list of units course.       }     } 

or both wrong!? appreciated.

cheers, ollie

few things. let me take through process, , might help.

start links , relationships. there's course, has units. each unit relates course unit. use relationship name. so:

{   “kind”: “clms#course”,   “id”: long,   “course-name”: string,   “course-icon”: string,   “product-name”: string,   “product-icon”: string,   “_links”: {     “self”: {“href” : string},      “unit”: [        {“href” : url-of-first-unit},        {“href” : url-of-second-unit},        {“href” : url-of-third-unit},        ...     ]   } } 

but unit not iana registered link relationship, should uri, or curried uri:

“_links”: {     “self”: {“href” : string},     "curies" : [        {"href" : "http://youndomain/rels/{rel}", name : "x" }     ],     “x:unit”: [        {“href” : url-of-first-unit},        {“href” : url-of-second-unit},        {“href” : url-of-third-unit},        ...     ]   } 

that's little confusing, makes unit "namespaced" , it's own thing good.

now realize retrieving of units individually painful. i'll assume in ui want show units right along courses, hal let's embed relationships:

{   “kind”: “clms#course”,   “id”: long,   “course-name”: string,   “course-icon”: string,   “product-name”: string,   “product-icon”: string,   “_links”: {     “self”: {“href” : string},      "curies" : [        {"href" : "http://youndomain/rels/{rel}", name : "x" }     ],     “x:unit”: [        {“href” : url-of-first-unit},        {“href” : url-of-second-unit},        {“href” : url-of-third-unit},        ...     ]   },   "_embedded" : {     “x:unit”: [        { json representing unit located @ url-of-first-unit},        { json representing unit located @ url-of-second-unit},        { json representing unit located @ url-of-third-unit},        ...     ]   } } 

now client can unit's checking embedded instead of checking links. in fact since it's embedded, there's no reason include links anymore (unless know client depending on them):

{   “kind”: “clms#course”,   “id”: long,   “course-name”: string,   “course-icon”: string,   “product-name”: string,   “product-icon”: string,   “_links”: {     “self”: {“href” : string},      "curies" : [        {"href" : "http://youndomain/rels/{rel}", name : "x" }     ],   },   "_embedded" : {     “x:unit”: [        { json representing unit located @ url-of-first-unit},        { json representing unit located @ url-of-second-unit},        { json representing unit located @ url-of-third-unit},        ...     ]   } } 

so client has them available embedded resource , not need retrieve resources http requests.

overall i'd suggest starting links everything, , optimize use cases embedded resources.

few notes:

• if have need collect units in single resource, perhaps consider page embedded item[s] units. relationship course page of unit[s] x:units.
• avoid having id field on resource unless id known outside world. self link better external id, it's url , easier turn actual resource.
• i prefer profile links opposed "kind" field, when looks enum. check out https://tools.ietf.org/html/rfc6906