首页 文章

标准的JSON API响应格式？

提问于
浏览 次
542

是否存在用于从API构造JSON响应的标准或最佳实践？显然每个应用程序的数据都是不同的，所以我不关心，而是“响应样板”，如果你愿意的话 . 我的意思的一个例子：

Successful request:

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

Failed request:

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

12 回答

  • 17

    我不会声称这是一个标准，因此我将使用“我更喜欢”的形式 .

    我更喜欢简洁的响应（当我要求一个JSON数组文章的/文章列表时） .

    在我的设计中，我使用HTTP进行状态报告， 200 只返回有效负载 .

    400 返回请求错误的消息：

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

    如果model / controler / URI不存在，则返回 404

    如果我的处理有错误，我会返回 501 并带有一条消息：

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

    从我所看到的，相当多的REST-ish框架往往是沿着这些方向 .

    Rationale ：

    JSON应该是一个 payload 格式，它认为JSend中有任何远程标准，尤其是其中没有更冗长的格式 . XHR将对HTTP响应做出反应，如果你为你的AJAX使用jQuery（像大多数人一样），你可以使用 try / catch 和 done() / fail() 回调来捕获错误 . 我无法看到JSON中的封装状态报告如何比这更有用 .

    回复于
  • 7

    假设您的问题是关于REST Web服务设计，更准确地说是关于成功/错误 .

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

    • 使用 only HTTP Status code 表示是否存在错误，并尝试将自己限制为标准错误（通常应该足够） .

    • 优点：这是一个独立于你的API的标准 .

    • 缺点：关于真实情况的信息较少 .

    • 使用 HTTP Status + json body （即使是错误） . 为错误定义统一的结构（例如：代码，消息，原因，类型等）并将其用于错误，如果成功则返回预期的json响应 .

    • 优点：仍然是标准的，因为您使用现有的HTTP状态代码并返回描述错误的json（您提供有关所发生情况的更多信息） .

    • 缺点：输出json将根据错误或成功而变化 .

    • Forget the http status （例如：总是状态200），总是使用json并在响应的根处添加一个布尔responseValid和一个错误对象（代码，消息等），如果是错误则将填充其他字段（成功） ）填充 .

    • 优点：客户端仅处理作为json字符串的响应主体并忽略状态（？） .

    • 缺点：标准较低 .

    这取决于你选择:)

    根据API我会选择2或3（我更喜欢2为json rest apis） . 我在设计REST Api时遇到的另一件事是文档对每个资源（url）的重要性：参数，正文，响应， Headers 等示例 .

    我还建议你使用jersey（jax-rs实现）genson（java / json数据绑定库） . 您只需在类路径中删除genson jersey并自动支持json .

    EDIT:

    • 解决方案2是最难实现的，但优势在于您可以很好地处理异常，而不仅仅是业务错误，初始工作更重要，但您可以长期获胜 .

    • 解决方案3在服务器端和客户端都很容易实现，但它不是很好，因为你必须在一个包含responseValid错误的响应对象中封装你想要返回的对象 .

    回复于
  • 137

    对于它的 Value ，我以不同的方式做到这一点 . 成功调用只有JSON对象 . 我不需要更高级别的JSON对象，其中包含指示true的成功字段和具有JSON对象的有效负载字段 . 我只返回适当的JSON对象，其中包含200或者在200范围内适用于 Headers 中HTTP状态的任何内容 .

    但是，如果出现错误（400系列中的某些内容），我将返回格式正确的JSON错误对象 . 例如，如果客户端使用电子邮件地址和电话号码对用户进行POST，并且其中一个格式不正确（即我无法将其插入到我的底层数据库中），我将返回如下内容：

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

    这里的重要部分是“field”属性必须与无法验证的JSON字段完全匹配 . 这允许客户确切地知道他们的请求出了什么问题 . 此外，“message”位于请求的区域设置中 . 如果“emailAddress”和“phoneNumber”都无效，则“errors”数组将包含两者的条目 . 409（冲突）JSON响应正文可能如下所示：

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

    使用HTTP状态代码和此JSON，客户端具有以确定性方式响应错误所需的全部内容，并且它不会创建尝试完成替换HTTP状态代码的新错误标准 . 请注意，这些仅发生在400个错误的范围内 . 对于200范围内的任何东西，我都可以返回任何合适的东西 . 对我来说就是这样通常是类似HAL的JSON对象，但这并不重要 .

    我想添加的一件事是“错误”数组条目中的数字错误代码或JSON对象本身的根 . 但到目前为止，我们还没有需要它 .

    回复于
  • 8

    移动开发人员可以轻松理解的最佳Web响应响应 .

    This is for "Success" Response

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

    This is for "Error" Response

    {
    "ReturnCode": "4",
    "ReturnMsg": "Invalid Username and Password",
    "ReturnValue": "",
    "Data": {}
}
    回复于
  • 8

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

    • JSON API - JSON API还包括创建和更新资源，而不仅仅是响应 .

    • JSend - 很简单，也许你正在做的事情 .

    • OData JSON Protocol - 非常复杂 .

    • HAL - 和OData一样，但是想成为HATEOAS .

    还有JSON API描述格式：

    回复于
  • 87

    JSON-RPC 2.0定义了标准的请求和响应格式，并且在使用REST API之后是一股清新的空气 .

    回复于
  • 16

    他们没有就大型软件巨头谷歌，Facebook，Twitter，亚马逊等公司的其他api响应格式达成一致，尽管上面的答案中提供了很多链接，有些人试图将响应格式标准化 .

    由于API的需求可能不同，因此很难让每个人都参与并同意某种格式 . 如果您有数百万用户使用您的API，为什么要更改您的响应格式？

    以下是我对谷歌，推特，亚马逊以及互联网上一些帖子启发的响应格式的看法：

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

    Swagger文件：

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

    回复于
  • 12

    Google JSON指南

    成功响应返回data

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

    错误响应返回error

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

    如果您的客户端是JS，您可以使用 if ("error" in response) {} 来检查是否有错误 .

    回复于
  • 513

    RFC 7807: Problem Details for HTTP APIs是目前我们对官方标准最接近的事情 .

    回复于
  • 4

    我猜一个事实标准还没有真正出现（也许永远不会） . 但无论如何，这是我的看法：

    Successful request:

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

    Failed request:

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

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

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

    回复于
  • -1

    以下是Instagram正在使用的json格式

    {
    "meta": {
         "error_type": "OAuthException",
         "code": 400,
         "error_message": "..."
    }
    "data": {
         ...
    },
    "pagination": {
         "next_url": "...",
         "next_max_id": "13872296"
    }
}
    回复于
  • 66

    JSON的观点是它完全动态且灵活 . 将它弯曲到您想要的任何想法，因为它只是一组序列化的JavaScript对象和数组，以单个节点为根 .

    rootnode的类型取决于你，它包含的内容取决于你，无论你发送元数据和响应是由你决定，你是否将mime-type设置为 application/json 或将其保留为 text/plain 取决于你（只要你知道如何处理边缘情况） .

    构建您喜欢的轻量级架构 .
    就个人而言，我发现分析跟踪和mp3 / ogg服务和图像库服务以及用于在线游戏的文本消息和网络数据包，以及博客帖子和博客评论 all 在发送的内容方面都有 very different requirements 收到什么以及如何消费 .

    因此，在完成所有这些工作时，我最不希望的是尝试使每个符合相同的样板标准，该标准基于XML2.0或其他一些标准 .

    也就是说，使用对 you 有意义的模式有很多要说的，并且经过深思熟虑 .
    只需阅读一些API回复，注意你喜欢什么，批评你不喜欢的东西，写下那些批评，理解为什么他们用错误的方式揉你，然后想想如何将你学到的东西应用到你需要的东西上 .

    回复于

相关问题