5

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?

Dave New
  • 34,265
  • 48
  • 183
  • 366

2 Answers2

6

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.

Jason Desrosiers
  • 15,196
  • 3
  • 34
  • 47
  • Your link to correlation methods seems to have rotted. Do those recommendations still exist in the current json-schema draft, and if so, which section? – dcorking Jan 24 '20 at 09:34
  • 1
    Thanks, @dcorking, I've fixed the link and updated the answer with changes from more recent drafts of JSON Schema. – Jason Desrosiers Jan 24 '20 at 14:46
0

Why not expose it on where it is called?

For example

schema/companies
schema/companies/10/employees

Change the api to schema

Kenichi Shibata
  • 148
  • 1
  • 11
  • 1
    If it is exposed at the resource URI, then employees (for example) requires the client to know a valid company ID (which also assume that the client is authenticated). There is no reason to secure the schema. This is something which could be available on public documentation. – Dave New Apr 18 '16 at 08:31