Находите спокойный ресурс при использовании HATEOAS?

Хорошо спроектированный HATEOAS API будет иметь четкие точки входа, и остальную часть поведения приложения можно будет обнаружить оттуда.

Поскольку вопрос касается HATEOAS, я бы сказал, что использование шаблона URI возлагает на клиента слишком большую ответственность. . Вместо этого вы должны указать явный URL-адрес для каждого допустимого действия над ресурсом с учетом текущего состояния приложения.

Это не просто стилистический момент. Если сервер предоставляет шаблон, то разработчик клиента должен написать код для заполнения шаблона, что создает связь между ними. Теперь вы не можете изменить структуру URL-адреса на стороне сервера, не нарушив контракт с его клиентами. С HATEOAS вы связываете URL-адрес с каждым действием, разрешенным на ресурсе, и клиент просто заботится о действии. URL-адрес фактически является непрозрачным дескриптором: "Выберите свое собственное приключение", как — говорит Ян Робинсон.

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

Помните, что то, что вы получаете по сети, — это всего лишь представление ресурса (REST расшифровывается как REpresentational State Transfer). Могут быть разные представления одного и того же ресурса в зависимости от вашего текущего контекста, скажем, вашего текущего набора разрешений и текущего состояния приложения. Разные представления могут правомерно предлагать разные последующие действия.

Используя ваш пример, владелец заказа может увидеть это:

{
  "id": "/api/v1/orders/123", // reference to the current resource
  "rel": {
    "cancel": {
      "url": "/api/v1/orders/cancel?order_id=123",
      "method": "POST",
      // Metadata about what the cancel operation returns...
    },
    "list_orders": {
      "url": "/api/v1/orders",
      "method": "GET",
      // Metadata about what the list_orders operation returns...
    },
    // ...
    // Other operations available to the owner
  },
  // ...
  // Order state
}

Здесь я определяю карту, которая использует ключ в качестве имени операции или отношение в терминологии HATEOAS, хотя я мог бы также иметь список карт с ключом с именем "rel" и значениями "cancel" и "list_orders" соответственно. .

Другая роль, например координатор доставки, может не видеть операцию cancel, поскольку у нее нет разрешения на отмену заказа.

Вы делаете это, используя ту же концепцию, что и в любом веб-приложении: отправляя клиенту рецепт для создания следующего запроса. В HTML для этого вы использовали бы HTML-форму. Если вы используете JSON, ваш формат должен иметь ту же концепцию, например. используя шаблон URI или даже форму, то есть список пар ключ-значение, возможно, с уже заполненными некоторыми значениями.

Например, предыдущий запрос может вернуть что-то вроде этого:

{ "order": {
    "link": {
        "template": "https://your-api.com/orders/{id}",
        "method": "GET",
        "type": "application/json"
    }
  }
}

Конечно, ваш код по-прежнему будет зависеть от некоторой информации — в данном случае от того факта, что идентификатор называется «id» в шаблоне. Но, добавляя эту косвенность, он не знает о фактическом URI. Также обратите внимание, что я добавил параметры метода и типа в качестве примера; решите ли вы сделать это настраиваемым, зависит от используемого вами формата. Для более подробного примера см. (или используйте) превосходный формат коллекция+json.

Хотя вы можете предоставить шаблон URI, я всегда считаю, что это немного запах, когда я должен это сделать. Иногда это необходимо, но если большая часть моего API использует этот подход, я бы не стал называть его HATEOAS или уровень 3 REST API.

Способ моделирования сценария во многом зависит от контекста, и, вероятно, поэтому Пит спрашивает о варианте использования.

Часто вы можете моделировать RESTful API так же, как вы моделируете веб-сайт, удобный для использования человеком. Например, у вас может быть ресурс, в котором перечислены все заказы пользователя, отсортированные, например. сначала самые последние заказы:

{
    "orders": [
        {
            "date": "2015-01-25",
            "total": 1234,
            "links": [
                {
                    "rel": "order",
                    "href": "https://follow.the.link"
                }
            ]
        },
        {
            "date": "2015-01-22",
            "total": 1337,
            "links": [
                {
                    "rel": "order",
                    "href": "https://follow.this.other.link"
                }
            ]
        }
    ]
}

Клиент может искать нужный ему заказ в этом списке, а затем, как только он идентифицирует интересующий заказ, может перейти по соответствующей ссылке с типом отношения «заказ».

В качестве общего ресурса Пособие по веб-сервисам RESTful незаменим для ответов на такого рода вопросы.

Возьмем вашу ситуацию. Они так, как я бы посмотрел на это. Ваш поиск всегда возвращает взаимодействие (например, URL). Затем клиент всегда может начать навигацию оттуда, чтобы получить данные.

Ключ в том, чтобы не возвращать значение, а только возвращать представление.

Мы используем платформу для этой реализации. Он имеет уникальный язык, основанный на взаимодействии. Платформа, поскольку она полностью совместима с HATEOAS, возвращает URL-адрес, когда на нее отправляется поиск.

В вашем примере, если мы отправим идентификатор бронирования. Он возвращает все URL-адреса заказов, которые имеют этот идентификатор бронирования. Затем клиент может перемещаться по этим URL-адресам.

Я надеюсь, что это поможет с вашим запросом.