REST API - включает в себя сведения о связанных объектах или только идентификаторы

Question

Какая лучшая практика проектирования?

Если у меня есть объект A, и он содержит некоторые связанные объекты, например, у меня есть объект car и его различные типы.

Должен ли я по запросу api.example.org/cars/1 отвечать только идентификаторами этих ресурсов (поэтому, если кому-то нужны подробности о них, требуется другой вызов API на api.example.org/type/1)

{
    "id": 1,
    "name": "Some Car",
    "types": [
        1,
        2
    ]
}

или укажите подробности об этих ресурсах

{
    "id": 1,
    "name": "Some Car",
    "types": [
        {
            "id": 1,
            "name": "Some Type",
            "something": "Blah"
        },
        {
            "id": 2,
            "name": "Some Type",
            "something": "Blah"
        }
    ]
}

Или укажите необязательный параметр, например «displayAll», а затем массив с именами параметров, которые должны быть получены все за один вызов API (в данном случае типов ).

Answer 1

Это касается одного из основных принципов REST, называемого HATEOAS (Гипермедиа как двигатель состояния приложения).

Идентификаторы объектов бесполезны и бессмысленны для клиентов. Что ты с ними делаешь? Кормить их функцией поиска? Построить новый URI с ними в конце? Позвоните по номеру 1-800 и спросите, что с ними делать? Распечатайте их на бумаге и отправьте по почте в государственное учреждение, которое поможет клиентам API найти следующие шаги?

Просто возвращайте полный URI, все время. Идентификатор, предоставленный клиенту, всегда должен быть URI - это то, что уникально идентифицирует рассматриваемый ресурс и может использоваться для его извлечения, обновления или удаления.

Answer 2

Я предпочитаю безпараметрическую версию варианта 1, но я бы предпочел что-то, где возвращается местоположение ресурса типа, чтобы клиент мог выбрать, извлекать ли эти ресурсы или нет.

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

{
    "id": 1,
    "name": "Some Car",
    "types": [
        {
            "location": "api.example.org/type/1"
        },
        {
            "location": "api.example.org/type/2"
        }
    ]
}