rest - 公开 API 端点的 JSON 模式？

Question

是否有关于在何处以及如何公开 API 端点模式的标准？

例如，假设以下 API 端点可用:

api/companies/

api/companies/{id}/employees/

公司和员工资源的架构应该在哪里公开？
api/company-schema.json和 api/employee-schema.json ?
api/schemas/company.json和 api/schemas/employee.json ?

Answer 1

您可以以任何您喜欢的方式设置您的架构端点，但您应该使用推荐的 correlation methods 之一。 .这个想法是没有用于访问模式的通用规则。相反，资源本身标识描述它的模式。

因此，请随意以任何您喜欢的方式公开您的模式。然后，如果需要，可以随意更改它，而不必担心破坏客户端实现。只需更改您的响应 header 以指向新模式，客户端应该能够动态处理更改。

最直接的关联方法是包含一个描述的链接头。

HTTP/1.1 200 OK
Content-Type: application/json
Link: </schema/companies>; rel="describedby"

{ ... }

另一种选择是使用 schema内容类型参数。 (注意:以前版本的 JSON Schema 使用 profile 而不是 schema )。

HTTP/1.1 200 OK
Content-Type: application/json; schema="/schema/companies"

{ ... }

然而， schema参数实际上并未为 application/json 定义媒体类型，因此该方法存在潜在的互操作性问题。这就是 application/schema-instance+json 的原因之一媒体类型被引入。它的工作原理就像 application/json ，但定义了一些普通 JSON 媒体类型没有的功能。

HTTP/1.1 200 OK
Content-Type: application/schema-instance+json; schema="/schema/companies"

{ ... }

编辑 2020/24/01 :修复断开的链接并更新答案以反射(reflect)最近草稿中的变化。