RESTful обработка подресурсов

Question

Я создаю RESTful-приложение и не знаю, как мне обрабатывать запросы, которые не возвращают все сущности ресурса или не возвращают несколько ресурсов (запрос GET /resource/all). Пожалуйста, позвольте мне несколько минут, чтобы настроить ситуацию (я постараюсь обобщить это как можно больше, чтобы оно могло относиться к другим, кроме меня):

Допустим, я создаю API продукта. Для простоты, допустим, он возвращает JSON (после того, как отправлены правильные заголовки accept). Продукты можно получить по адресу /product/[id]. У продуктов есть обзоры, к которым можно получить доступ в /products/[id]/review/[id].

Мой первый вопрос заключается в этом шаблоне подресурса. Поскольку вам не всегда нужны отзывы при получении продукта, они доступны по другому URI. Из того, что я прочитал, я должен включить URI запроса, который будет возвращать все отзывы URI для продукта, в ответ на запрос продукта. Как мне поступить так, чтобы оно соответствовало стандартам RESTful? Должен ли это быть заголовок типа Reviews-URI: /product/123/review/all или я должен включить URL-адрес в тело ответа следующим образом:

{ 'name': 'Shamwow',
  'price': '$14.99',
  'reviews': '/product/123/review/all'
}

Мой второй вопрос о том, как должен работать запрос /product/[id]/review/all. Я слышал, что я должен просто отправить URL-адреса всех обзоров и заставить пользователя ПОЛУЧИТЬ каждый из них, а не упаковывать их все в один запрос. Как мне указать этот массив URI для проверки в соответствии со стандартами RESTful? Должен ли я использовать заголовок или список URI в теле ответа следующим образом:

{ 'reviews': [ '/product/123/review/1',
               '/product/123/review/2',
               '/product/123/review/3'
             ]
}

Answer 1

Ваша проблема в том, что вы не используете Hypermedia. Hypermedia, в частности, имеет элементы, которые содержат ссылки на другие вещи.

Вы должны рассмотреть HAL , так как это тип гипермедиа контента, который также присутствует в JSON.

Затем вы можете использовать ссылки в HAL для предоставления ссылок на ваши обзоры.

Answer 2

Здесь вам может помочь стандарт JSON Schema , в частности, гипер-схемы.

Это позволяет вам определить, как извлекать URI ссылок из ваших данных, и каковы их "rel" - по сути, превращая ваши данные JSON в гипер-медиа. Итак, для вашего первого бита данных вы можете написать схему вроде:

{
    "title": "Product",
    "type": "object",
    "properties": {...},
    "links": [
        {"rel": "reviews", "href": "{reviews}"}
    ]
}

Значение href является шаблоном URI - так, например, если ваши данные включают productId, тогда вы можете заменить значение href на "/product/{productId}/review/all".

Для второго примера данных (списка обзоров) у вас может быть такая схема:

{
    "type": "object",
    "properties": {
        "reviews": {
            "type": "array",
            "items": {
                "links": [
                    {"rel": "full", "href": "{$}"}
                ]
            }
        }
    }
}

В шаблоне URI href специальное значение {$} означает «значение самого узла JSON». Таким образом, Hyper-Schema указывает, что каждый элемент в массиве reviews должен быть заменен данными по указанному URL (rel="full").

Answer 3

Что касается вашего первого вопроса (заголовок или текст), определенно не придумывайте свой собственный заголовок. Некоторые здесь утверждают, что вы должны использовать заголовок Link , но я думаю, что вы найдете много необходимости во вложенных ссылках и должны держать их в теле.

То, как вы указываете URI для ресурса reviews/ или список URI в нем, полностью зависит от типа носителя, который вы выбираете для представления каждого ресурса. Например, если вы используете HTML, вы можете использовать тег привязки. Если вы используете обычный JSON, у которого нет синтаксиса гипермедиа, вам придется потратить некоторое время на документацию для вашего API, описывающую, какие значения являются URI, либо назначая их специальными ключами, либо заключая их в специальный синтаксис, такой как {"link": "reviews/123"} или со связанным документом схемы.

Взгляните на Shoji , тип носителя на основе JSON, который был специально разработан для этого шаблона субресурсов.