Существуют ли стандарты или лучшие практики для структурирования ответов JSON из API? Очевидно, что данные каждого приложения различны, так что меня это не касается, а скорее «шаблон ответа», если хотите. Пример того, что я имею в виду:

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

{
  "success": true,
  "payload": {
    /* Application-specific data would go here. */
  }
}

Неудачный запрос:

{
  "success": false,
  "payload": {
    /* Application-specific data would go here. */
  },
  "error": {
    "code": 123,
    "message": "An error occurred!"
  }
}

Да, есть пара стандартов (хотя и с определенными свободами в определении стандарта):

1. JSON API - JSON API охватывает также создание и обновление ресурсов, а не только ответы.
2. JSend - Простой и, вероятно, то, что вы уже делаете.
3. OData JSON Protocol - очень сложный.
4. HAL - как OData, но стремится быть как HATEOAS .

Есть также форматы описания JSON API:

• развязность
  • Схема JSON (используется Swagger, но вы можете использовать его отдельно)
• WADL в JSON
• RAML
• HAL, потому что HATEOAS в теории самоописывает себя.

Руководство по Google JSON

Возвращение ответа успеха data

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

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

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

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

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

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

{
  "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"
}

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

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

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

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

1. Используйте только код статуса HTTP, чтобы указать, была ли ошибка, и попытайтесь ограничить себя стандартными (обычно этого должно быть достаточно).

   • Плюсы: это стандарт, независимый от вашего API.
   • Минусы: меньше информации о том, что на самом деле произошло.

2. Используйте HTTP Status + json body (даже если это ошибка). Определите единую структуру для ошибок (например: код, сообщение, причина, тип и т. Д.) И используйте ее для ошибок, если она успешна, просто верните ожидаемый ответ json.

   • Плюсы: все еще стандартно, так как вы используете существующие коды состояния HTTP и возвращаете json с описанием ошибки (вы предоставляете больше информации о том, что произошло).
   • Минусы: выходной JSON будет варьироваться в зависимости от того, если это ошибка или успех.

3. Забудьте статус http (например, всегда status 200), всегда используйте json и добавляйте в корень ответа логический responseValid и объект ошибки (код, сообщение и т. Д.), Который будет заполнен, если это ошибка, в противном случае другие поля (успех) заселены.

   • Плюсы: клиент имеет дело только с телом ответа, который является строкой json, и игнорирует статус (?).

   • Минусы: менее стандартные.

Выбор за вами :)

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

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

РЕДАКТИРОВАТЬ:

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

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

RFC 7807: Проблема Деталь для HTTP API , на данный момент ближе всего мы должны официальный стандарт.

Следующее - формат Instagram, который использует Instagram

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

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

Я предпочитаю краткий ответ (при запросе списка / статей я хочу массив статей 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 состоял в том, чтобы поцеловать его и придерживаться HTTP. Я не думаю, что в JSend есть что-то отдаленно стандартное, особенно среди более многословных. XHR будет реагировать на HTTP-ответ, если вы используете jQuery для своего AJAX (как это делают большинство), вы можете использовать try/ catchи done()/ fail()callbacks для захвата ошибок. Я не вижу, как инкапсуляция отчетов о состоянии в JSON более полезна, чем эта.

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

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

{
  "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, но здесь это не имеет значения.

Единственное, что я подумал о добавлении, это числовой код ошибки либо в записях массива «errors», либо в корне самого объекта 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

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

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

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

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

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

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

Для тех, кто придет позже, в дополнение к принятому ответу, который включает HAL, JSend и JSON API, я бы добавил несколько других спецификаций, на которые стоит обратить внимание:

• JSON-LD , который является Рекомендацией W3C и определяет, как создавать совместимые веб-сервисы в JSON
• Ion Hypermedia Type для REST, который заявляет о себе как «простой и интуитивно понятный гипермедиа тип на основе JSON для REST»

Предлагаемая базовая структура выглядит хорошо, но объект ошибки, как он определен, слишком ограничен. Часто для выражения проблемы нельзя использовать одно значение, а вместо этого нужна цепочка проблем и причин .

Я провел небольшое исследование и обнаружил, что наиболее распространенным форматом для возврата ошибки (исключения) является структура этой формы:

{
   "success": false,
   "error": {
      "code": "400",
      "message": "main error message here",
      "target": "approx what the error came from",
      "details": [
         {
            "code": "23-098a",
            "message": "Disk drive has frozen up again.  It needs to be replaced",
            "target": "not sure what the target is"
         }
      ],
      "innererror": {
         "trace": [ ... ],
         "context": [ ... ]
      }
   }
}

Это формат, предложенный стандартом OASIS для данных OASIS OData, и он, кажется, является наиболее стандартным вариантом, однако пока не наблюдается высоких показателей принятия какого-либо стандарта. Этот формат соответствует спецификации JSON-RPC.

Вы можете найти полную библиотеку с открытым исходным кодом, которая реализует это по адресу: Mendocino JSON Utilities . Эта библиотека поддерживает объекты JSON, а также исключения.

Подробности обсуждаются в моем блоге об обработке ошибок в JSON REST API.

Нет никакого закона о нарушении закона или закона вне закона, кроме здравого смысла. Если мы абстрагируем это как два человека, говорящих, стандарт - лучший способ, которым они могут точно понимать друг друга в минимальных словах за минимальное время. В нашем случае «минимальные слова» оптимизируют полосу пропускания для эффективности транспорта, а «точное понимание» является структурой для эффективности анализатора; что в итоге приводит к тому, что данных становится меньше, а общая структура; так что он может пройти через отверстие для булавки и может быть проанализирован через общий объем (по крайней мере, на начальном этапе).

Почти во всех предложенных случаях я вижу отдельные ответы для сценария «Успех» и «Ошибка», что для меня является двусмысленной. Если ответы в этих двух случаях различны, то почему нам действительно нужно поставить флаг «Успех»? Разве не очевидно, что отсутствие «ошибки» является «успехом»? Возможно ли получить ответ, в котором «Успех» равен «ИСТИНА» с установленным «Ошибка»? Или, кстати, «Успех» - ЛОЖЬ, а «Ошибка» не установлена? Только одного флага недостаточно? Я бы предпочел иметь только флаг «Ошибка», потому что я считаю, что будет меньше «Ошибка», чем «Успех».

Кроме того, мы должны действительно сделать флаг «Ошибка»? Что делать, если я хочу ответить с несколькими ошибками проверки? Итак, я считаю более эффективным иметь узел «Ошибка» с каждой ошибкой как дочерней по отношению к этому узлу; где пустой (считается до нуля) узел «Ошибка» будет означать «Успех».

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

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

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

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

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