时间戳

首页 > 解决方案 > Rest API 最佳实践返回单个字符串与将其包装在 JSON 对象中？

json - Rest API 最佳实践返回单个字符串与将其包装在 JSON 对象中？

问题描述

我有一个可以返回几种状态之一的端点，例如“活动”、“取消”等。

在响应中将其作为字符串返回是不好的做法，例如：

"Active"

还是应该将其包装在 JSON 对象中，例如：

{
    "status": "Active"
}

标签： jsonrest

解决方案

JSON当前注册的参考是RFC 8259

JSON 值必须是对象、数组、数字或字符串，或以下三个文字名称之一：

  • 错误的
  • 无效的
  • 真的

因此，当这是您的资源的自然表示时，返回带引号的字符串很好。

事情有可能变得复杂：稍后发现资源的自然表示是消息，而不是字符串。

使用对象的理由是它使我们能够灵活地向模式引入向后兼容的更改，以便我们可以包含更多信息，而不会破坏只知道原始模式的客户端。当您的表示“只是”一个字符串时，这要困难得多。

但这是一种折衷：当您只需要一根弦时，您为未来的灵活性付出的代价是稍微不方便处理。

如果您控制所有 API 使用者，并且可以与模式同步更改使用者，那么您可以从简单的答案开始，如果您需要更复杂的表示，则投入工作来解决所有问题。

如果您无法控制客户，或者进行同步更改成本高昂，那么这个计划就没有那么吸引人了。

如果您正在创建一个外部公开的 API，那么您不太可能控制所有客户端。

也就是说，通过精心设计，您还可以选择仅引入新资源来涵盖您实际需要具有多个值的消息的情况。

我在这里最强烈的建议：无论你走哪条路，都要留下纸迹。 记录您在做出选择时所知道的一切，以及您预计未来的风险和并发症。这样，将来您将能够恢复您的决定的上下文。

推荐阅读