Как правильно представить страничные ресурсы с HAL?

Question

Это звучит как вопрос новичка, но мне интересно, как лучше представить страничные ресурсы в формате HAL? Сейчас я использую Spring HATEOAS API для конвертации Page объект в ресурс PagedResourcesAssembler#toResource(Page<T>, ResourceAssembler<T,R>), Это приводит к следующему выводу:

{
"_links": {
    "self": {
        "href": "http://example.org/api/user?page=3"
    },
    …
}
"count": 3,
"total": 498,
"_embedded": {
    "users": [
        {
            "_links": {
                "self": {
                    "href": "http://example.org/api/user/mwop"
                }
            },
            "id": "mwop",
            "name": "Matthew Weier O'Phinney"
        }
    ]
}

}

Все работает нормально, но единственная проблема - возвращаемая коллекция находится под _embedded поле и имеет имя класса, так что клиент должен знать это имя класса, не так ли? Будет ли лучше просто вернуть коллекцию под content как не-HAL формат? Если да, как мне добиться этого с помощью Spring HATEOAS?

Answer 1

Это не проблема, это способ _embedded определяется в спецификации HAL.

users это не класс, это отношение ссылки, которое позволит клиентам фактически найти запрашиваемую коллекцию в первую очередь (например, используя выражение JSONPath). Это не что-то неожиданное, но обычно такое же отношение ссылок, которое клиент обычно использовал для поиска этого ресурса.

Предположим, что корень API выставляет этот документ:

{
  "_links": {
    "users": {
      "href": "…"
    },
    …
  }
}

Видя это, клиент должен знать семантику users чтобы найти ссылку, по которой он хочет перейти. В твоем случае users в основном указывает на ресурс коллекции, который поддерживает нумерацию страниц.

Так что, если клиент переходит по ссылке users, затем он может найти актуальный контент, который ищет _embedded.users в ответе HAL путем объединения знаний о типе носителя (HAL, _embedded) и семантика уровня приложения службы (users).