HATEOAS и формы, управляемые API

В вашем примере кажется, что Connections — это ресурсы. Не совсем ясно, действительно ли Orders являются ресурсами. Я предполагаю, что да, но чтобы иметь Order, вам нужны Client и Connection. Итак, чтобы создать Order, вам нужно будет открыть коллекцию, скорее всего, из Client или Connection, возможно, из обоих.

Я думаю, что разрыв связан с мышлением типа «теперь, когда у нас есть список доступных подключений, клиент может выбрать одно из них и создать Order». Это совершенно верно, но это мышление удаленного вызова процедур (RPC), а не REST. Ни один из них объективно не лучше другого, за исключением контекста определенного набора требований проекта, и, как правило, их не следует смешивать вместе.

С мышлением RPC определяется метод создания заказа (например, с использованием OpenAPI), и ожидается, что любые клиенты будут использовать некоторую внеполосную информацию для определения требуемой правильной формы (например, путем чтения спецификации OpenAPI).

С мышлением REST/HATEOAS правильным подходом будет предоставление коллекции Orders из Connection. У каждого Connection в коллекции есть ссылка self и коллекция Orders (ссылка или объект в соответствии с требованиями приложения). Каждый элемент Order имеет ссылку self, и именно здесь указаны возможности. Order — это известный тип (даже с REST/HATEOAS клиент и сервис должны, по крайней мере, согласовать общий словарь), который клиент предположительно знает, как определить. Этот словарь можно определить с помощью любого работающего механизма — json-ld, XSD и т. д.

HATEOAS требует, чтобы результат содержал все, что нужно клиенту для обновления состояния. Не может быть внеполосной информации (кроме общего словаря). Итак, чтобы решить вашу проблему, вам нужно либо предоставить коллекцию Order из Connection, либо разрешить создание Order путем публикации в Connection. Если последнее кажется чем-то вроде взлома, вероятно, так оно и есть.

Например, в HAL-Forms я бы сделал что-то вроде:

{
  "connections": [{
    "id": "aaa",
    "carrier": "Fast Bus",
    "price": 3.20,
    "departure": "2019-04-05T12:30"
    "_links": { 
      "self": { ... }, // link to this connection
      "orders": {} // link to collection of orders for this connection
    }
  },
  , ...],
  "_links": {
    "self": { ... } // link to the collection
  },
  "_templates": { ... } // post/put/patch/delete connection
}

Клиенты переходили по ссылкам на orders и оттуда получали _templates коллекцию, содержащую инструкции по управлению Order ресурсами. Для Order POST, скорее всего, потребуется идентификатор соединения и информация о клиенте. Спецификация HAL-форм определяет свойство регулярного выражения, которое можно использовать для указания типа данных, предоставляемых для любого конкретного элемента формы. Поскольку вы достигли заказа, перейдя по определенному соединению, вы сможете указать в своем _templates для этого заказа, какие именно поля необходимы. например /orders?connectionType=aaa вернет другой набор обязательных свойств, чем /orders?connectionType=bbb, но оба используют одну и ту же self ссылку /orders?connectionType = {type}, и вы должны проверить ее при POST/PUT/PATCH.

Я должен отметить, что Spring-HATEOAS выходит за рамки спецификации HAL-Forms и позволяет использовать несколько _links и _templates. См. эта проблема GitHub.

Может показаться, что HATEOAS/REST требует немного больше работы, чем простой API OpenAPI/RPC, и это действительно так. Но то, от чего вы отказываетесь в простоте, вы приобретаете в гибкости и отказоустойчивости, предполагая хорошо продуманных клиентов. Какой подход является правильным, зависит от множества факторов, большинство из которых не являются техническими (навыки команды, ожидаемые потребители, насколько вы контролируете клиентов, техническое обслуживание и т. д.).