REST - типизированные ресурсы против классов HYDRA - PullRequest
Новая
       21

REST - типизированные ресурсы против классов HYDRA

0 голосов
/ 26 октября 2018

Из статьи Филдинга (https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven):

REST API никогда не должен иметь «типизированных» ресурсов, значимых для клиента. Авторы спецификаций могут использовать типы ресурсов для описания реализации сервера за интерфейсом,но эти типы должны быть нерелевантными и невидимыми для клиента. Единственными типами, которые являются значимыми для клиента, являются тип носителя текущего представления и стандартизированные имена отношений. [ditto]

В HYDRA классы могут бытьдокументировано в документации API, как это: 

supportedClass:
  '@id': 'schema:Event'
    supportedProperty:
      - property:
          '@id': eventName

Разве это не считается типизированным ресурсом? В JSON-LD есть даже поле @type. Я понимаю важность стандартизированных имен отношений, так как онипредоставить клиентам семантику, формат и ограничения, необходимые для полезной работы с ресурсом или свойством, однако, ограничивая диапазон возможных отношений в документации API, мы действительно объявляем типы (классы).

Без классов, клиенты не будут знать, какие отношенияне будет присутствовать, и кодирование клиента так, чтобы он знал большинство типов отношений (например, из schema.org), не практично.

Каково точное значение этого ограничения и как оно может быть полезнона практике? Разве HYDRA не уважает это?

Я спрашиваю это из теоретического интереса.На практике мне все равно, удовлетворяет ли мой HTTP API всем ограничениям, если его можно использовать.

1 Ответ

0 голосов
/ 31 октября 2018

Мне кажется, я понимаю разницу между «типизированными ресурсами» (как их называет Филдинг) и типами или классами, определенными в медиа-типах, таких как JSON-LD / HYDRA. Я отвечаю на свой вопрос, но, если необходимо, расширите / исправьте его.

TL; DR Насколько я понимаю, это ограничение относится к типам как предопределенным представлениям (или структурам) ресурса и рекомендует документировать возможные отношения и правила обработки медиа-типов вместо этой структуры. Эти отношения все еще могут быть сгруппированы в «типы», но представление не будет жестким.

Свойства обычно имеют предопределенные имена и понимаются в контексте их включающего типа. Это означает, что сервер / клиент должен согласовать это соглашение об именах для обработки этих типов, и поле, названное одинаково в одном типе и в другом типе, может иметь совершенно другую семантику. Это дает жесткую структуру для ресурсов.

С другой стороны, гипермедийные типы, такие как JSON-LD, не используют свойства обычным способом. Вместо этого они используют некоторую встроенную информацию (@context) для определения семантики свойств, которые могут быть другими сущностями, объектами значений, ссылками и т. Д. *

Обрабатывая ресурс с данным типом гипермедиа, свойства преобразуются в некоторые четко определенные отношения, обычно определяемые в словаре. Это означает, что одно и то же отношение может быть повторно использовано для нескольких типов, например, поля name в Person и Book могут ссылаться на отношение https://schema.org/name между ними и объектами значений (например, простыми именами строк).

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

Например: 

{
  "@context": "http://schema.org/",
  "@type": "Person",
  "@id": "http://srv.org/users/1",
  "name": "Jane Doe",
  "telephone": "(425) 123-4567",
  "url": "http://www.janedoe.com"
}

- это тот же ресурс, что и 

{
  "@context": {
    "a": "http://schema.org/name",
    "b": "http://schema.org/telephone",
    "c": {
      "@id": "http://schema.org/url",
      "@type": "@id"
    }
  },
  "@type": "http://schema.org/Person",
  "@id": "http://srv.org/users/1",
  "a": "Jane Doe",
  "b": "(425) 123-4567",
  "c": "http://www.janedoe.com"
}

или даже как 

[
  {
    "@id": "http://srv.org/users/1",
    "@type": [
      "http://schema.org/Person"
    ],
    "http://schema.org/name": [
      {
        "@value": "Jane Doe"
      }
    ],
    "http://schema.org/telephone": [
      {
        "@value": "(425) 123-4567"
      }
    ],
    "http://schema.org/url": [
      {
        "@id": "http://www.janedoe.com"
      }
    ]
  }
]
...