公开 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

为什么不在调用它的地方公开它？

例如

schema/companies
schema/companies/10/employees

将api更改为架构

Answer 2

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

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

最直接的相关方法是包括 Link header 描述的。

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

{ ... }

另一种选择是使用 schema content-type 参数。（注意：以前版本的 JSON 模式使用 profile 而不是 schema）。

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

{ ... }

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

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

{ ... }

编辑 2020/24/01：修复损坏的 link 并更新答案以反映最近草稿中的更改。

Answer 3

我将使用 Link header 并将这些作为 url

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

公开 API 端点的 JSON 架构？

Exposing the JSON Schema for API endpoints?

rest

jsonschema

json-api