это - json pure apis




Стандартный формат ответа JSON API? (8)

Существуют ли стандарты или передовая практика для структурирования ответов 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!"
  }
}

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

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

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

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

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

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


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

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

Существуют также форматы описания JSON API:

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

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

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

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

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

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

Ниже приведена иконка json format, использующая

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

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

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

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

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

    • Плюсы: по-прежнему стандарт, когда вы используете существующие коды состояния HTTP, и вы возвращаете json, описывающий ошибку (вы предоставляете больше информации о том, что произошло).
    • Минусы: выход json будет меняться в зависимости от ошибки или успеха.
  3. Забудьте о статусе http (например: всегда статус 200), всегда используйте json и добавьте в корневой ответ ответ булевский ответ Valid и объект ошибки (код, сообщение и т. Д.), Который будет заполнен, если это ошибка, иначе другие поля (успех).

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

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

Это зависит от вас, чтобы выбрать :)

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

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

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

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

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


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

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

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

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

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


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

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


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







response