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

{ ... }

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