REST JSON API 可选参数设计答案

【问题标题】：REST JSON API optional parameters designREST JSON API 可选参数设计
【发布时间】：2016-04-03 07:55:41
【问题描述】：

我们的目标是开发 API，您可以在其中 POST /data/save/ 接受一些 JSON 数据，如下所示。 JSON 应包含以下属性之一的主要要求： “属性 1”、“属性 2”、“属性 3”。即当一个属性存在时，另一个属性不应该存在。

{
   "name": "test name",
   "attribute1": [
       "test1", "test2"
    ]
    or
    "attribute2": [
        "test3", "test4"
     ]
     or
     "attribute3": true
}

问题是如何正确设计这样的 API，使其易于使用且不会被客户端混淆。

最好了解一些在这个方向上的最佳实践。

【问题讨论】：

标签： json rest jackson

【解决方案1】：

custom media type 应该说明如何使用您的 API。它应该指定要在您的请求中包含的内容。

另一种解决方案可能是，像这样构建请求：

{
   "name": "test name",
   "attr-key": "my-attribute1",
   "values": ["test1", "test2"]
}

【讨论】：

不鼓励介绍媒体类型。

【解决方案2】：

我同意这样的 API 会让客户端感到困惑。

什么是创建不同的端点：

POST /data/save/attribute1 json_1

POST /data/save/attribute2 json_2

【讨论】：

【解决方案3】：

我会返回一个

400 错误请求

由于格式错误，服务器无法理解请求句法。客户端不应该重复请求修改。

以及解释不支持多个属性的短语。

【讨论】：

谢谢！我想这将是我们案例的最佳选择，以支持可选属性。因为通过验证支持一个端点而不是几个端点会更容易。