公开API端点的JSON Schema？

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

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

一个典型的例子

请求

GET /api/companies
Accept: application/json

响应

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

{ ... }

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

Answer 2

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

例如

schema/companies
schema/companies/10/employees

将api更改为架构