Включение/вставка vs. ссылки в API RESTful

Таким образом, общий шаблон для RESTful API - это возврат одного объекта со встроенными ссылками, которые вы можете использовать для извлечения связанных объектов. Но иногда для удобства вы хотите сразу отбросить целую кучу объекта-объекта.

Например, скажем, у вас есть приложение хранилища с клиентами, заказы и возвращает. Вы хотите отобразить личную информацию, все заказы и все возвраты вместе для идентификатора клиента 12345. (Предположительно, есть веские причины не всегда возвращать заказы и возвраты с личной информацией клиента.)

Чистый RESTful способ сделать это:

  • GET /
    • возвращает список шаблонов ссылок, в том числе запрос для клиентов
  • GET /customers/12345 (на основе шаблона ссылки из /)
    • возвращает персональную информацию клиента
    • возвращает ссылки для получения этих заказов клиентов и возвращает
  • GET /orders?customerId=12345 (от ответа /customers/12345)
    • получает заказы для клиента 12345
  • GET /returns?customerId=12345 (от ответа /customers/12345)
    • получает доход для клиента 12345

Но было бы неплохо, если у вас есть URI customers, чтобы иметь возможность вернуть все это в один запрос. Существует ли наилучшая практика для такого рода запросов удобства, где вы хотите перекрыть некоторые или все ссылки вместо того, чтобы делать несколько запросов? Я думаю что-то вроде:

GET /customers/12345?include=orders,returns

но если есть способ, которым люди это делают, я лучше не буду что-то делать.

(FWIW, я не строю магазин, поэтому не будем спорить о том, являются ли это подходящими объектами для модели или как вы собираетесь переходить к фактическим продуктам или что-то еще.)

Обновлено для добавления: Похоже, что в HAL говорят, что они называются "встроенными ресурсами", но в приведенных примерах нет Кажется, что нет способа выбрать, какие ресурсы встраивать. Я нашел одно сообщение в блоге, предлагая что-то вроде описанного выше, используя embed в качестве параметра запроса:

GET /ticket/12?embed=customer.name,assigned_user

Является ли эта стандартная или полустандартная практика, или только что-то составило один блоггер?

Ответы

Ответ 1

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

Тем не менее, если вы ищете вдохновение, вы можете проверить, что делает OData с параметром $expand и смоделировать вашу ссылку отношение из тот. Имейте в виду, что вы все равно должны четко определить контракт своих отношений, иначе клиентские программисты могут увидеть соглашение, подобное OData, и предположить (ошибочно), что ваше приложение полностью совместимо с OData и будет вести себя как один.