是否存在从API构建JSON响应的标准或最佳实践?显然,每个应用程序的数据都是不同的,所以我不太关心,而是“响应样板”,如果你愿意的话。我的意思是:

成功的请求:

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

当前回答

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

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

仅使用HTTP状态代码来指示是否存在错误,并尝试将自己限制在标准状态(通常这就足够了)。优点:它是一个独立于api的标准。缺点:关于真实发生的事情的信息较少。使用HTTP Status+json主体(即使是错误)。为错误定义一个统一的结构(例如:代码、消息、原因、类型等),并将其用于错误,如果成功,则返回预期的json响应。优点:仍然是标准的,因为您使用现有的HTTP状态代码,并返回一个描述错误的json(您提供了有关发生的更多信息)。缺点:输出json会因错误或成功而有所不同。忘记http状态(例如:always status 200),始终使用json,并在响应的根位置添加一个布尔responseValid和一个错误对象(代码、消息等),如果是错误,将填充该对象,否则将填充其他字段(成功)。优点:客户端只处理作为json字符串的响应主体,而忽略状态(?)。缺点:标准越低。

这取决于您的选择:)

根据API的不同,我会选择2或3(对于json rest API,我更喜欢2)。我在设计RESTApi时经历的另一件事是每个资源(url)的文档的重要性:参数、主体、响应、头等+示例。

我还建议您使用jersey(jax-rs实现)+genson(java/json数据绑定库)。您只需在类路径中删除genson+jersey,就会自动支持json。

编辑:

解决方案2是最难实现的,但它的优点是,您可以很好地处理异常,而不仅仅是业务错误,最初的努力更重要,但从长远来看,您会赢得胜利。解决方案3在服务器端和客户端都很容易实现,但它并不是很好,因为您必须将要返回的对象封装在包含responseValid+错误的响应对象中。

其他回答

我将此结构用于REST API:

{
  "success": false,
  "response": {
    "data": [],
    "pagination": {}
  },
  "errors": [
    {
      "code": 500,
      "message": "server 500 Error"
    }
  ]
}

是的,出现了一些标准(尽管在标准定义上有些自由):

JSON API-JSON API还包括创建和更新资源,而不仅仅是响应。JSend-简单,可能是您已经在做的事情。OData JSON协议-非常复杂。哈尔-像OData,但目标是像HATEOAS。

还有JSON API描述格式:

大摇大摆JSON模式(swagger使用,但可以单独使用)JSON格式的WADL冲压,冲压HAL,因为理论上HATEOAS是自我描述的。

我想事实上的标准还没有真正出现(可能永远不会)。但无论如何,我的看法是:

成功的请求:

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

优势:成功和错误案例中的顶级元素相同

缺点:没有错误代码,但如果您愿意,您可以将状态更改为(成功或失败)代码,或者-您可以添加另一个名为“代码”的顶级项。

Google JSON指南

成功响应返回数据

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

错误响应返回错误

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

如果您的客户端是JS,则可以使用if(响应中的“error”){}来检查是否存在错误。

对于后面的内容,除了包括HAL、JSend和JSON API的公认答案之外,我还将添加一些其他值得研究的规范:

JSON-LD,它是W3C推荐标准,规定了如何以JSON构建可互操作的Web服务Ion Hypermedia Type for REST,自称是“一种简单直观的基于JSON的REST超媒体类型”