公开 API 端点的 JSON 模式？答案

【问题标题】：Exposing the JSON Schema for API endpoints?公开 API 端点的 JSON 模式？
【发布时间】：2016-08-09 20:14:32
【问题描述】：

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

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

api/companies/

api/companies/{id}/employees/

公司和员工资源的架构应该在哪里公开？

api/company-schema.json 和 api/employee-schema.json?

api/schemas/company.json 和 api/schemas/employee.json?

【问题讨论】：

标签： rest jsonschema json-api

【解决方案1】：

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

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

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

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

{ ... }

另一个选项是使用schema content-type 参数。（注意：以前版本的 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"

{ ... }

EDIT 2020/24/01：修复损坏的链接并更新答案以反映最近草稿的变化。

【讨论】：

您与相关方法的链接似乎已损坏。这些建议是否仍然存在于当前的 json-schema 草案中，如果存在，是哪个部分？
谢谢，@dcorking，我已经修复了链接，并根据最近的 JSON Schema 草案的更改更新了答案。

【解决方案2】：

为什么不把它暴露在调用它的地方呢？

例如

schema/companies
schema/companies/10/employees

将 api 更改为架构

【讨论】：

如果它在资源 URI 中公开，则员工（例如）要求客户端知道有效的公司 ID（这也假定客户端已通过身份验证）。没有理由保护架构。这可以在公共文档中找到。

【解决方案3】：

我将使用带有这些作为 url 的 Link 标头

/api/companies.schema
/api/companies/{id}/employees.schema

【讨论】：