问题
Is there a standard to where and how to expose the schema of API endpoints?
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
and api/employee-schema.json
?
api/schemas/company.json
and api/schemas/employee.json
?
回答1:
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.
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"
{ ... }
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"
{ ... }
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: Fix broken link and update answer to reflect changes in recent drafts.
回答2:
Why not expose it on where it is called?
For example
schema/companies
schema/companies/10/employees
Change the api to schema
来源:https://stackoverflow.com/questions/36688091/exposing-the-json-schema-for-api-endpoints