Как правильно использовать HAL (язык приложений Hypermedia) _embedded?

Question

Я создаю REST API, который предоставляет пользователям информацию о онлайн-курсах. Вот общая структура курса:

курсы> Units> Уроки> Мероприятие

Я пытаюсь сделать мою структуру ответа JSON HAL совместимой, но я не уверен, если я делаю это правильно.

Какой из следующих верна:

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

Или ссылка на список единиц _embedded ресурсов?

{ 
     “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} // This is a link to list of units for the course. 
     } 
    } 

Или оба неправильно !? Любая помощь оценивается.

Приветствия, Олли

Answer 1

Немного вещей. Позвольте мне провести вас через этот процесс, и это может помочь.

Начните с ссылок и их отношений. Есть курс, у него есть единицы. Таким образом, каждая единица относится к курсу как единое целое. используйте это как ваше имя отношения. так:

{ 
    “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}, 
     ... 
    ] 
    } 
} 

но блок не IANA зарегистрирован ссылка отношения, поэтому он должен быть на самом деле URI, или кэрри к 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}, 
     ... 
    ] 
    } 

, это немного сбивает с толку, но делает это так, ваше подразделение «с именами», и это собственная вещь, которая хороша.

Теперь осознайте, что получение всех этих единиц индивидуально было бы болезненным. Я предполагаю, что в вашем пользовательском интерфейсе вы хотите, чтобы показать единицы измерения прямо наряду с курсами, так HAL давайте встраивать эти отношения:

{ 
    “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”: [ 
     { some json representing the unit located at url-of-first-unit}, 
     { some json representing the unit located at url-of-second-unit}, 
     { some json representing the unit located at url-of-third-unit}, 
     ... 
    ] 
    } 
} 

Теперь клиент может получить блок поживает моя проверку встроенные вместо проверки ссылок. На самом деле, так как он был встроен, там действительно нет оснований включать ссылки больше (если вы не знаете, клиент в зависимости от них):

{ 
    “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”: [ 
     { some json representing the unit located at url-of-first-unit}, 
     { some json representing the unit located at url-of-second-unit}, 
     { some json representing the unit located at url-of-third-unit}, 
     ... 
    ] 
    } 
} 

Так что теперь клиент имеет их в виде внедренного ресурса и не нужно извлекать ресурсы с помощью HTTP-запросов.

В целом я предлагаю начать со ссылок ко всему и оптимизировать для ваших случаев использования встроенными ресурсами.

Лишние ноты:

• Если у вас действительно есть необходимость собрать все блоки вместе в одного ресурса, возможно, считают, что в качестве страницы со встроенным пункта [ов], которые были бы единица , Отношение от курса к странице единицы [s], вероятно, будет x: единицей.
• Избегайте иметь поле идентификатора на вашем ресурсе, если идентификатор не является тем, что известно внешнему миру. Самостоятельная ссылка - намного лучший внешний идентификатор, так как это URL-адрес и проще превратить в реальный ресурс.
• Я предпочитаю ссылки на профили, а не поля вида, особенно когда это похоже на перечисление. выписка https://tools.ietf.org/html/rfc6906