Я не буду так самоуверен, что утвержу, что это стандарт, поэтому я буду использовать форму «Я предпочитаю».

Я предпочитаю сложный ответ (при запросе списка / статей мне нужен массив статей JSON).

В моих проектах я использую протокол HTTP для отчета о состоянии, 200 возвращает только полезную нагрузку.

400 возвращает сообщение о том, что было неправильно с запросом:

{"message" : "Missing parameter: 'param'"}

Возврат 404, если модель / контроллер / URI не существует

Если есть была ошибка обработки на моей стороне, я возвращаю 501 с сообщением:

{"message" : "Could not connect to data store."}

Из того, что я видел, довольно много структур REST-ish, как правило, находятся в этих строках.

Обоснование:

Предполагается, что JSON является форматом полезной нагрузки, это не протокол сеанса. Вся идея многословных полезных данных сеанса происходит из мира XML / SOAP и различных ошибочных вариантов, которые создавали эти раздутые проекты. После того, как мы поняли, что все это было массивной головной болью, весь смысл REST / JSON заключался в том, чтобы KISS его и придерживаться HTTP. Я не думаю, что в JSend есть что-либо удаленно standard , и особенно не с более подробным из них. XHR будет реагировать на HTTP-ответ, если вы используете jQuery для своего AJAX (как и большинство других), вы можете использовать обратные вызовы try / catch и done() / fail() для захвата ошибок. Я не вижу, как инкапсуляция отчетов о состоянии в JSON более полезна.

Они не согласны с остальными api-ответами больших гигантов программного обеспечения - Google, Facebook, Twitter, Amazon и других, хотя в приведенных выше ответах было указано много ссылок, в которых некоторые люди пытались стандартизировать формат ответа.

Поскольку потребности API могут отличаться, очень сложно получить всех на борту и согласиться на какой-то формат. Если у вас есть миллионы пользователей, использующих ваш API, почему вы измените свой формат ответа?

Ниже приводится мой формат ответа, вдохновленный Google, Twitter, Amazon и некоторыми сообщениями в Интернете:

https://github.com/adnan-kamili/rest-api-response-format

Файл Swagger:

https : //github.com/adnan-kamili/swagger-sample-template

RFC 7807: Информация о проблемах для HTTP API в настоящий момент является самым близким к официальному стандарту.

JSON-RPC 2.0 определяет стандартный формат запроса и ответа и представляет собой глоток свежего воздуха после работы с API REST.

Предполагая, что вы задаете вопрос о дизайне веб-сервисов REST и точнее относительно успеха / ошибки.

Я думаю, что существует 3 разных типа дизайна.

1. Использовать только статус HTTP чтобы указать, была ли ошибка, и попытаться ограничить себя стандартными (обычно этого должно быть достаточно). Плюсы: Это стандарт, независимый от вашего api. Минусы: меньше информации о том, что на самом деле произошло.
2. Использовать статус HTTP Status + json (даже если это ошибка). Определите единую структуру для ошибок (например, код, сообщение, причину, тип и т. Д.) И используйте ее для ошибок, если это будет успешным, тогда просто верните ожидаемый ответ json. Плюсы: по-прежнему стандарт, когда вы используете существующие коды состояния HTTP, и вы возвращаете json, описывающий ошибку (вы предоставляете больше информации о том, что произошло). Минусы: выход json будет меняться в зависимости от ошибки или успеха.
3. Забудьте о статусе http (например: всегда статус 200), всегда используйте json и добавьте в корневой части ответа логический responseValid и объект ошибки (код, сообщение и т. д.), который будет заполнен, если он является ошибкой, иначе будут заполнены другие поля (успех). Плюсы: клиент имеет дело только с телом ответа, который является json-строкой и игнорирует статус (?). Минусы: чем меньше стандарт.

Вам решать:)

В зависимости от API я бы выбрал 2 или 3 (предпочитаю 2 для json rest apis). Еще одна вещь, которую я испытал при разработке REST Api, - это важность документации для каждого ресурса (url): параметры, тело, ответ, заголовки и т. Д. + Примеры.

Я также рекомендовал бы использовать jersey (реализация jax-rs) + genson (java / json databinding library). Вам нужно только удалить genson + jersey в вашем пути к классу, и json автоматически поддерживается.

EDIT:

• Решение 2 сложнее всего реализовать, но преимущество в том, что вы можете
• Решение 3 легко реализовать как на стороне сервера, так и на стороне клиента, но это не так приятно, как вы должен будет инкапсулировать объекты, которые вы хотите вернуть, в объект ответа, содержащий также ошибку responseValid +.

Лучший ответ для веб-apis, который можно легко понять разработчикам мобильных устройств.

Это для ответа «Успех»

{  
   "ReturnCode":"1",
   "ReturnMsg":"Successfull Transaction",
   "ReturnValue":"",
   "Data":{  
      "EmployeeName":"Admin",
      "EmployeeID":1
   }
}

Это для ответа «Ошибка»

{
    "ReturnCode": "4",
    "ReturnMsg": "Invalid Username and Password",
    "ReturnValue": "",
    "Data": {}
}

Google JSON guide

Ответ отклика ответа data

{
  "data": {
    "id": 1001,
    "name": "Wing"
  }
}

Ответ об ошибке ответа error

{
  "error": {
    "code": 404,
    "message": "ID not found"
  }
}

, и если ваш клиент JS, вы можете использовать if ("error" in response) {}, чтобы проверить, есть ли ошибка.

Ниже показана json format instagram с использованием

{
    "meta": {
         "error_type": "OAuthException",
         "code": 400,
         "error_message": "..."
    }
    "data": {
         ...
    },
    "pagination": {
         "next_url": "...",
         "next_max_id": "13872296"
    }
}

Точка JSON заключается в том, что она полностью динамична и гибка. Согните его по какому-либо прихоти, потому что это всего лишь набор сериализованных объектов JavaScript и массивов, внедренных в один узел.

Какой тип корневого каталога зависит от вас, то, что он содержит, до того, отправляете ли вы метаданные вместе с ответом, зависит ли вы задаете тип mime application/json или оставьте его как text/plain до вас (если вы знаете, как обращаться с краем случаев).

Создайте легкую схему, которая вам нравится. Лично я обнаружил, что отслеживание аналитики и поддержка mp3 / ogg и изображений, а также текстовые сообщения и сетевые пакеты для онлайн-игр, а также записи в блогах и комментарии к блогам имеют очень разные требования в терминах того, что отправлено и что получено, и как их следует потреблять.

Итак, последнее, что я хотел бы, когда все это делать, - попытаться заставить каждого из них соответствовать тот же стандартный шаблон, который основан на XML2.0 или somesuch.

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

Для чего это стоит, я делаю это по-другому. У успешного вызова есть только объекты JSON. Мне не нужен объект JSON более высокого уровня, который содержит поле успеха, указывающее true и поле полезной нагрузки, которое имеет объект JSON. Я просто возвращаю соответствующий объект JSON с 200 или любым, что подходит в диапазоне 200 для статуса HTTP в заголовке.

Однако, если есть ошибка (что-то из семейства 400), я возвращаю хорошо сформированный объект ошибки JSON. Например, если клиент выполняет POSTING пользователя с адресом электронной почты и номером телефона, и один из них неверен (т.е. я не могу вставить его в мою базовую базу данных), я верну что-то вроде этого:

{
  "description" : "Validation Failed"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Invalid phone number."
  } ],
}

Важные биты здесь состоят в том, что свойство «field» должно соответствовать полю JSON, которое не может быть проверено. Это позволяет клиентам точно знать, что пошло не так с их запросом. Кроме того, «сообщение» находится в локали запроса. Если оба «emailAddress» и «phoneNumber» были недопустимыми, массив «errors» будет содержать записи для обоих. Тело ответа JSON 409 (конфликт) может выглядеть так:

{
  "description" : "Already Exists"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Phone number already exists for another user."
  } ],
}

С кодом статуса HTTP и этим JSON у клиента есть все, что им нужно, чтобы ответить на ошибки детерминированным способом и не создавать новый стандарт ошибок, который пытается завершить замену кодов состояния HTTP. Обратите внимание, что это происходит только в диапазоне 400 ошибок. Для чего-либо в диапазоне 200 я могу просто вернуть все, что подходит. Для меня это часто HAL-подобный объект JSON, но на самом деле это не имеет никакого значения.

Единственное, что я подумал о добавлении, - это числовой код ошибки либо в записях массива «ошибки», либо в корень самого объекта JSON. Но пока нам это не нужно.

Я думаю, что стандарт defacto действительно не появился (и, возможно, никогда). Но независимо от того, вот мой прием:

Успешный запрос:

{
  "status": "success",
  "data": {
    /* Application-specific data would go here. */
  },
  "message": null /* Or optional success message */
}

Сбой запроса:

{
  "status": "error",
  "data": null, /* or optional error payload */
  "message": "Error xyz has occurred"
}

Преимущество: те же элементы верхнего уровня в обоих успехах и ошибки

Недостаток: нет кода ошибки, но если вы хотите, вы можете либо изменить статус как код (успех или неудачу), либо вы можете добавить еще один элемент верхнего уровня с именем «code», .