Предоставление схемы JSON для конечных точек API?

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 

Response

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

{ ... } 

Таким образом, не стесняйтесь выставлять свои схемы так, как вам нравится. И тогда не стесняйтесь изменять его, если вам нужно, не опасаясь нарушать реализацию клиента. Просто измените заголовки ответов, чтобы указать на новую схему, и клиенты должны иметь возможность обрабатывать изменения динамически.

Answer 2

Почему бы не разоблачить его там, где он называется?

Например

schema/companies 
schema/companies/10/employees 

Изменение апи к схеме