标准JSON API响应格式？(Standard JSON API response format?

DO标准或最佳实践的结构化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!"
  }
}

Answer 1:

是的，有一对夫妇的标准（尽管在标准的定义，一些自由）已经出现：

1. JSON API - JSON API包括创建和更新资源，而不仅仅是响应。
2. JSEND -简单，也许你已经在做的事情。
3. OData的JSON协议 -非常复杂。
4. HAL - OData的一样，但目标是成为HATEOAS喜欢。

也有JSON API描述格式：

• 昂首阔步
  • JSON模式 （使用招摇，但你可以使用它独立）
• WADL在JSON
• 肾错构瘤
• HAL因为HATEOAS在理论上是自描述。

Answer 2:

谷歌JSON指南

成功响应返回data

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

错误响应返回error

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

如果你的客户是JS，你可以使用if ("error" in response) {}以检查是否存在错误。

Answer 3:

我想一个事实上的标准还没有真正出现（而且可能永远不会）。 但无论如何，这是我的看法：

成功的请求：

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

优势：在成功和错误的情况下相同的顶级元素

缺点：没有错误代码，但如果你愿意，你可以改变现状是一个（成功或失败）的代码， - 或者你可以添加一个名为“代码”另一个顶级项目。

Answer 4:

假设你的问题是关于REST Web服务设计和更精确的关于成功/错误。

我认为有3种不同类型的设计。

1. 只使用HTTP状态代码 ，表明如果有一个错误，并尝试限制自己的标准的人（通常应该足够了）。

   • 优点：这是你的API的标准独立。
   • 缺点：对究竟发生了什么资料较少。

2. 使用HTTP状态+ JSON体 （即使是错误的）。 定义错误的统一结构（例如：代码，消息，原因，类型等），并使用它的错误，如果它是成功的然后就返回预期的JSON响应。

   • 优点：当你使用现有的HTTP状态代码，并返回错误描述（你提供了什么事更多信息）一个JSON仍然是标准的。
   • 缺点：输出JSON将根据变化，如果它是一个错误或成功。

3. 忘记http状态 （例如：总是状态200），始终使用JSON，并在该将被填充，如果它是一个错误，否则其他字段的响应的布尔responseValid和一个错误对象（代码，消息等）的根添加（成功）的填充。

   • 优点：仅是一个JSON字符串，并忽略状态的响应主体的客户端交易（？）。

   • 缺点：不太标准。

它是由你来选择:)

根据API我会选择2或3（我更喜欢2 JSON的REST API）。 我在设计REST API经历了另一件事情是文档的每个资源（URL）的重要性：参数，身体的反应，头部等+例子。

我也建议你使用的球衣（JAX-RS实现）+ genson （爪哇/ JSON数据绑定库）。 你只需要下降genson +球衣在类路径和JSON是自动支持。

编辑：

• 方案2是最难实现的，但好处是，你可以很好地处理了异常，不仅是企业的错误，最初的努力更重要，但你赢得长远。

• 方案三是落实两个，服务器端和客户端的容易的，但它不是那么好，你将不得不封装要在还含有responseValid +错误的响应对象返回的对象。

Answer 5:

声称这是一个标准的，所以我会用“我喜欢”的形式，我不会狂妄自大。

我喜欢简洁的响应（请求的/文章我想文章的JSON数组列表时）。

在我的设计我使用HTTP的状态报告，200点返回有效载荷。

400返回哪些是错的请求的消息：

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

返回404，如果模型/ CONTROLER / URI不存在

如果有跟在我身边的处理错误，我返回501消息：

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

从我所看到的相当一些REST十岁上下的框架往往是沿着这些路线。

理由 ：

JSON被认为是有效载荷的格式，它不是一个会话协议。 冗长的会议十岁上下的有效载荷的整个构思来自XML / SOAP世界和各种选择，误导创建那些臃肿的设​​计。 之后，我们意识到这一切是一个巨大的头痛，休息整点/ JSON是吻它，并坚持HTTP。 我不认为有任何东西在任何远程JSEND 标准 ，尤其不能与它们之间的更详细。 XHR将反应HTTP响应，如果你使用jQuery你AJAX（最喜欢做），你可以使用try / catch和done() / fail()回调捕获错误。 我看不出在封装JSON状态报告是比这更加有用。

Answer 6:

以下是JSON格式的Instagram使用

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

Answer 7:

对于什么是值得我这样做是不同的。 一个成功的调用只是有JSON对象。 我并不需要包含一个领域的成功表明真实的，有JSON对象的有效载荷领域的更高层次的JSON对象。 我只用200或无论是在范围200在报头中的HTTP状态适当返回适当的JSON对象。

但是，如果有错误（某事在400家），我返回一个结构良好的JSON错误对象。 例如，如果客户端在张贴的电子邮件地址和电话号码，其中一个用户的格式不正确（即我不能将它插入到我的底层数据库），我将返回是这样的：

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

重要位这里是“田”属性必须JSON的领域正是无法验证匹配。 这使客户能够知道到底是什么出了毛病，他们的请求。 另外，“信息”是在请求的区域设置。 如果这两个“EMAILADDRESS”和“phoneNumber的”是无效的，则“错误”数组将包含两个条目。 409（冲突）JSON响应体可能是这样的：

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

随着HTTP状态代码，这JSON客户端有他们需要以确定的方式响应错误的，它不会产生任何试图完成替代HTTP状态代码的新的误差标准。 请注意，这只是发生400错误的范围。 对于在200范围内的任何我可以只返回什么是适当的。 对我来说，它往往是一个HAL般的JSON对象但这并不重要位置。

的一件事我考虑增加是一个数字错误代码无论是在所述的“错误”阵列条目或JSON对象本身的根。 但到目前为止，我们还没有需要它。

Answer 8:

在RFC 7807：用于HTTP API的问题详细信息是在目前我们有一个正式的标准最接近。

Answer 9:

他们是在大的软件巨头的REST API响应格式没有达成一致 - 谷歌，Facebook，Twitter的，亚马逊和其他人，尽管许多环节都在上面的答案，其中一些人曾试图以规范的响应格式已经提供。

作为API的需求可能不同是很难得到大家在船上，并同意一些格式。 如果你有百万使用API​​的用户，为什么你会改变你的回应格式？

以下是我对互联网上的灵感来自谷歌，Twitter的，亚马逊和一些帖子的响应格式：

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

扬鞭文件：

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

Answer 10:

JSON的一点是，它是完全动态的，灵活的。 弯曲它到任何你心血来潮想，因为它只是一组序列化的JavaScript对象和数组，植根于单个节点。

什么根节点的类型是你的，它所包含的内容是你的，你是否与响应一起发送元数据是你的，不管你设置的MIME类型application/json或把它作为text/plain是你（只要你知道如何处理的边缘情况）。

建立一个你喜欢的轻量级架构。
就个人而言，我发现，分析，跟踪和MP3 / OGG服务和图像库中的是什么方面的服务和支持短信和网络数据包进行在线游戏和博客，帖文，博客，评论都有着非常不同的要求发送和接收什么，以及应该如何被消耗。

所以，过去的事情我会想，做这一切的时候，就是尽量让每一个符合相同的样板标准，它是基于XML2.0或诸如此类。

这就是说，有很多关于使用模式这对你有意义并且是经过深思熟虑的可说。
刚看了一些API响应，请注意你喜欢什么，批评什么，你不这样做，写那些批评下来，明白他们为什么擦你走错了路，然后想想如何应用你学会了你所需要的。

Answer 11:

JSON-RPC 2.0定义了一个标准的请求和响应的格式，和是的新鲜空气REST API的工作之后的呼吸。

Answer 12:

我做了一些研究，发现返回错误（例外）是最常见的格式是这种形式的结构：

{
   "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规范是一致的。

你可以发现，在实现这个完整的开放源码库： 门多西诺JSON实用程序 。 该库支持JSON对象以及例外。

细节在我的博客文章中讨论的错误处理JSON REST API

Answer 13:

对于网络的API，可以很容易地通过移动开发者了解最好的回应。

这是“成功”响应

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

这是一个“错误”响应

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

文章来源: Standard JSON API response format?