公开API端点的JSON模式? [英] Exposing the JSON Schema for API endpoints?

问题描述

在哪里以及如何公开API端点的模式是否存在标准?

Is there a standard to where and how to expose the schema of API endpoints?

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

For example, let's say the following API endpoints are available:

api/companies/

api/companies/{id}/employees/

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

Where should the schema for the company and employee resources be exposed?

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

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

推荐答案

您可以按照自己的喜好设置模式端点，但是您应该使用推荐的

You can setup your schema endpoints any way you like, but you should use one of the recommended correlation methods. The idea is that there is no universal rule for accessing schemas. Instead, the resource itself identifies the schema that describes it.

因此，可以随意公开自己喜欢的任何模式.然后，如有需要，可以随时进行更改，而不必担心破坏客户端实现.只需更改您的响应标头以指向新的架构，客户端就应该能够动态处理更改.

So, feel free to expose your schemas any way you like. And then feel free to change it if you need to without fear of breaking client implementations. Just change your response headers to point to the new schema and clients should be able to handle the change dynamically.

最直接的相关方法是包含一个由Link标头描述的内容.

The most straightforward correlation method is to include a describedby Link header.

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

{ ... }

另一个选择是使用schema content-type参数. (注意:JSON Schema的早期版本使用profile而不是schema).

The other option is to use the schema content-type parameter. (Note: Previous versions of JSON Schema used profile instead of schema).

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

{ ... }

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

However, the schema parameter is not actually defined for the application/json media-type, so there are potential interoperability issues with that method. That's one reason why the application/schema-instance+json media type was introduced. It works just like application/json, but defines a few capabilities that the normal JSON media-type doesn't.

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

{ ... }

EDIT 2020/24/01 :修复断开的链接并更新答案以反映最新草稿中的更改.

EDIT 2020/24/01: Fix broken link and update answer to reflect changes in recent drafts.

这篇关于公开API端点的JSON模式?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！