我什么时候应该 return Json-schema 来防止 out-of-band 将知识转移到 REST API 客户端？

Question

在 PoC 阶段开发 HATEOAS REST API。关注 json-schema 的所有架构。我期待客户使用这个模式来巧妙地动态创建表单以创建新资源。只是不确定什么时候 return 呢？

可能的选项可以是：

return 它作为 link 到 _schema 下的另一个关系（如 _self）
return 它在 OPTIONS 上（不相信，因为 OPTIONS 不可缓存并且应该仅用于代理和 cors 类型的发现）
return 每当预期用户可能会创建新资源时的完整资源架构（但它可能会增加负载，而不是每次用户都想创建时）
return 如果 GET 请求带有自定义 header 寻找模式。
您可以想到的任何其他智能选项:)

Answer 1

不需要自定义 header。这就是 Accept header 的用途。客户应在 Accept header 中指定他们想要的格式。如果您使用的是 HATEOAS，您还应该定义自己的 media-types，因为这是客户将拥有的唯一 out-of-band 信息，但如果您使用的是通用 media-types，您可以 return json-schema 用于 application/schema+json 和简单的 json 用于 application/json.

Answer 2

JSON 架构文档包括两个将文档与架构相关联的建议。

第一个也是最受欢迎的是使用 profile Content-Type header 属性。

Content-Type: application/my-media-type+json; profile="http://example.com/my-hyper-schema#"

另一个建议（我从未真正看到有人使用过）是 Link header 和 rel=describedBy。

Link: <http://example.com/my-hyper-schema#>; rel="describedBy"

参考：http://json-schema.org/latest/json-schema-core.html#anchor33

我什么时候应该 return Json-schema 来防止 out-of-band 将知识转移到 REST API 客户端？

When should I return a Json-schema to prevent out-of-band transfer of knowledge to REST API client?

rest

jsonschema

hateoas