JSON Hyper-Schema：GET 和 POST 的不同模式

Question

我想描述一个 API，它的字段允许在发布项目时以不同的方式定义值，但只能以一种特定的方式在字段中输出。

例如，我可能想描述一个 API，其中可以像这样创建或更新项目：{"name": "Task", "due": "2014-12-31"} 或像这样：{"name": "Task", "due": {"$date": 1419984000000}}，但它只会以第一种方式从 API 返回。

因此 POST/PUT 的架构可能是：

{
    "type": "object"
    "properties": {
        "name": {
            "type": "string"
        },
        "due": {
            "oneOf": [
                {
                    "type": "string",
                    "format": "date"
                },
                {
                    "type": "object",
                    "properties": {
                        "$date": {
                            "type": "number"
                        }
                    },
                    "required": ["$date"],
                    "additionalProperties": false
                }
            ]
        }
    }
}

而通过 GET 访问的架构会简单得多：

{
    "type": "object"
    "properties": {
        "name": {
            "type": "string"
        },
        "due": {
            "type": "string",
            "format": "date"
        }
    }
}

API 的使用者最好知道他们只需要考虑一种可能的输出方法，而不是所有的输出方法。

是否有任何公认的标准方法来指定 JSON 超模式上下文中的不同模式？我曾考虑通过"links" 属性指定这些差异，但我不知道"rel" 我会在什么下定义这些架构，而且看起来非常不标准。

Answer 1

如果我理解正确，并且您想为每个操作指定一个架构，您可以使用标准超架构来完成。让我们看一下 post 操作的示例：

{
  "description": "create an item.",
  "href": "/items",
  "method": "POST",
  "rel": "create",
  "schema": {
    "$ref": "#/api/createitem"
  },
  "title": "Create an item"
}

所需的实际架构通过“$ref”在“schema”属性中引用。

如果您还想描述响应类型，则可以使用“targetSchema”属性。请注意，这只是建议性的（因为它是explained in the docs）