Должен ли мой API вкладывать данные JSON в родительский объект?

Сегодня меня назвали «непрофессионалом», потому что я не вложил свой ответ JSON в родительский объект.

GET /users/{id} отвечает так:

{
    "username":"atr217",
    "age":35,
    ...
}

Они ожидали этого:

{
    "user":{
        "username":"atr217",
        "age":35,
        ...
    }
}

Или, может быть, это:

{
    "status":200,
    "message":"OK"
    "data":{
        "username":"atr217",
        "age":35,
        ...
    }
}

Я видел, как это делается в обоих направлениях. Является ли наилучшей практикой перенос данных в родителя? Если да, то почему? А что еще входит в родитель?

Я использую SwaggerHub и OpenAPI 3, если это имеет значение.


json api rest openapi swagger
person Tylor Hess    schedule 23.10.2018    source источник
comment
Возможный дубликат корневых узлов в JSON   -  person Helen    schedule 24.10.2018
comment
status и "message":"OK"/or any other полностью избыточны, поскольку мы можем получить их из ответа HTTP. В общем, вся информация, которую можно получить из HTTP-ответа, избыточна в данных ответа, все остальное зависит от соблюдения соглашений (команда, передовой опыт, который все согласились использовать и т. д.), но в конце концов спорный.   -  person lealceldeiro    schedule 24.10.2018
comment
рассмотрите возможность использования jsonapi.org   -  person Tylor Hess    schedule 25.10.2018

Ответы (1)


arrow_upward
4
arrow_downward

Я нашел правильный поисковый запрос Google: "конверт"

Советы по разработке RESTful API из опыта

«Я не люблю обволакивать данные. Он просто вводит еще один ключ для навигации по потенциально плотному дереву данных. Метаинформация должна быть в заголовках».

«Одним из аргументов в пользу вложения данных является предоставление двух разных корневых ключей, указывающих на успешность ответа, данных и ошибок. Однако я делегирую это различие кодам состояния HTTP в случае ошибок».

«Изначально я считал, что обертывать данные не обязательно, и что HTTP сам по себе обеспечивает адекватную «оболочку» для доставки ответа. Однако… теперь я рекомендую обертывать».

Когда в моем REST API следует использовать конверт? Если я использую его в одном месте, должен ли я использовать его всегда?

«HTTP — это ваш конверт… Сказав это, нет ничего плохого в описательном тексте ответа»

Рекомендации по разработке практичного RESTful API

«Не используйте конверт по умолчанию, но делайте это возможным при необходимости»

«Мы можем защитить API в будущем, оставаясь свободными от конвертов по умолчанию и применяя конверты только в исключительных случаях».

«Есть 2 ситуации, когда конверт действительно нужен — если API нужно поддерживать междоменные запросы по JSONP или если клиент не умеет работать с HTTP-заголовками».

«Любящие конверты API обычно включают данные разбиения на страницы в сам конверт. И я их не виню - до недавнего времени лучших вариантов было не так много. Правильный способ включить детали разбивки на страницы сегодня — это использовать заголовок Link, представленный в RFC 5988».

person Tylor Hess    schedule 24.10.2018