Создание клиентской библиотеки HATEOAS

Question

Предположим, что у меня есть RESTful API для управления заказами, которая использует HAL для облегчения HATEOAS:

GET /orders/2 
    { 
    "_links": { 
     "self": "/orders/2", 
     "items": "/orders/2/items" 
    }, 
    "subtotal": 30.0, 
    "shipped": false 
    } 

Я хочу написать мой клиент (приложение) с помощью набора интерфейсов, так что, если предположить, что реализация этих интерфейсов DI-d/построена на заводах DI-d и т. д., я действительно не хочу (хочу) заботиться о том, что они поддерживаются моим RESTful API. В качестве примера (псевдо C#/Java):

public interface Order { 
    public void addItem(Item item); 
    public float getSubtotal(); 
    public boolean getShipped(); 
} 

Order order = ...; 
Item item = ...; 
order.addItem(item); 
...(order.getSubtotal())...; 

Мой вопрос: могу ли я/это имеет смысл для создания реализаций интерфейса с API в Order/Item? Под этим я подразумеваю аналогично тому, что предлагается с C#/веб-сервисами, которые экспортируют WSDL.

Я думал о реализации OPTIONS для таких ресурсов, как /orders и /orders/{id}, так что я бы эффективно иметь API HATEOAS для обхода схемы в API:

GET /orders/* (I'd need a suitable wildcard of course) 
    { 
    "_links": { 
     "addItem": { 
     "href": "/orders/{id}/items", 
     "templated": true, 
     "type": "method" 
     } 
    } 
    } 

Конечно, я мог бы сделать это часть объекта _links, возвращаемого с любым данным ресурсом (например, /orders/2), но это исключает статическое создание кода.

Мне интересно, есть ли разумный способ инкапсулировать тот факт, что если предоставляется конкретная ссылка, соответствующее действие должно быть доступно/выполнено, в противном случае нет.

Примечание: В случае, если это имеет значение, я фактически работаю в JavaScript (в частности, с AngularJS). Тем не менее, я все равно хотел бы написать свое приложение, используя набор концептуальных интерфейсов/контрактов.

Answer 1

Мой вопрос: могу ли я/это имеет смысл для создания реализаций интерфейса заказа/товара от API? Под этим я подразумеваю способ , аналогичный тому, который предлагается с C#/веб-сервисами, которые экспортируют WSDL.

Это отчасти имеет смысл. С помощью простого CRUD API вы можете сопоставить ресурсы с объектами. По сложным приложениям это не работает, потому что вы нанесли URI s на resource s и METHOD URI пар на operation s. Поэтому каждый раз, если вам нужна операция, не определенная HTTP, вам необходимо создать новый ресурс или, по крайней мере, новый URI для уже существующего ресурса.

Некоторые примеры:

• перевод денег с одного счета на другой: POST /transfer [acc1, acc2, amount, currency] - передача не необходимое существование в качестве юридического лица в своей области логики (не пытаются такого рода решения в производстве код, если только вам хочу банкротства: D)
• отправки по электронной почте другому пользователю: POST /messages [recipient, message]
• можно сопоставить ресурсы на стоимость объектов тоже: GET /users/123/address
• вы можете использовать идентификаторы URI для отображения уменьшить коллекцию: GET /users?name="John"
• вы можете использовать PUT /users/123 [details] вместо POST /users [details], чтобы создать новый пользователь
• вы можете использовать POST /player/123/xp/increment 10 вместо PUT /player/123/xp [xp+10] обновить очки опыта игрока

О WSDL, как решения, которые вы можете прочитать намного больше здесь: Third Generation Web APIs - Markus Lanthaler.

Мое личное мнение, что он не стоит усилий для создания такой системы, поскольку у нее больше недостатков, чем преимуществ.