Тип гипермедиа HAL + JSON не является типом мультимедиа для REST?

Можно ли использовать тип гипермедиа HAL+JSON для создания службы RESTful?

Из того, что я прочитал, клиенту RESTful API не нужно обрабатывать разные ресурсы с особыми случаями. Вместо этого тип носителя следует использовать для описания ожидаемого вида ресурсов.

В спецификации HAL приводится следующий пример:

GET /orders

{
  ...
  "shippedToday": 20,
  ...
}

```

Как клиент этого примера HAL+JSON-serving API, мне, похоже, нужно знать, что «заказ» имеет атрибут shippedToday. Кажется, это противоречит тому ограничению, что клиенту не нужно понимать синтаксис представления.

Это не критика HAL. Вопрос в том, чтобы помочь моему (и другим) пониманию дизайна RESTful API.


api media-type restful-architecture
person edev    schedule 28.07.2016    source источник

Ответы (1)


arrow_upward
0
arrow_downward

Можно ли использовать тип гипермедиа HAL+JSON для создания службы RESTful?

Определенно да.

API должен иметь URL-адрес рекламного щита, который в вашем случае может быть /.

Это точка входа, с которой люди, а в идеале даже машины могут начать изучать ваш API.

Согласно спецификации HAL представление ресурсов содержит необязательное свойство называется "_links", который описан здесь:

Это объект, имена свойств которого являются типами связи (как определено в RFC5988), а значения либо объект ссылки, либо массив объектов ссылки.

Таким образом, эти ссылки представляют гипермедиа часть вашего API. Отношения могут быть зарегистрированными в IANA, или вы можете использовать ваши собственные отношения расширения.

Отношения не должны быть двусмысленными. Их имена должны быть уникальными. Вот почему рекомендуется использовать URI из вашего собственного домена в качестве имен для ваших собственных отношений. Эти URI идентифицируют ресурс, который представляет отношение и содержит документацию API, читаемую человеком или машиной документацию вашего отношения.

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

Вот пример ответа на запрос GET / HTTP/1.1:

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
    "_links": {
        "self": { "href": "/" },
        "http://yourdomain.com/docs/rels/orders": { "href": "/orders" },
    }
}

Под http://yourdomain.com/docs/rels/orders должна быть документация по API.

person leifbattermann    schedule 18.01.2017
comment
Я читал это пару раз, и на самом деле это не способствует моему пониманию того, что предоставляет HAL _links. Вы говорите, что я должен понять из свойств _links, что я должен прочитать документацию, представленную в /docs/rels/orders, чтобы узнать, как URL-адрес /orders представляет собой набор конечных точек HAL, предлагающих функциональность CRUD для заказов? Мне просто кажется нелогичным, что я должен использовать метку свойства в качестве URL-адреса. - person Adam; 06.03.2017
comment
@ Адам Да, это действительно немного нелогично. И ваше понимание этого правильно, насколько я могу судить. Чтобы сделать типы отношений ссылок более удобочитаемыми, вы можете использовать CURIE (см. stateless.co/hal_specification.html). . - person leifbattermann; 07.03.2017