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

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

0 голосов
/ 24 октября 2018

Меня сегодня назвали "непрофессионалом", потому что я не вложил свой ответ 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, если это имеет значение.

1 Ответ

0 голосов
/ 24 октября 2018

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

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

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

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

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

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

«HTTP - это ваш конверт ... Сказав это, нет ничего плохого в том, чтобы иметь описательный текст ответа»

Лучшие практики для разработки прагматического API RESTful

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

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

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

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

...