APIエンドポイントのスキーマを公開する場所と方法の標準はありますか？会社と従業員のリソースのスキーマを露出しなければならないAPIエンドポイント用のJSONスキーマを公開していますか？
api/companies/
api/companies/{id}/employees/
：
たとえば、のは、以下のAPIエンドポイントが利用できるとしましょうか？
api/company-schema.jsonおよびapi/employee-schema.json？
api/schemas/company.jsonおよびapi/schemas/employee.json？
へのAPIがありますが、推奨相関法[1]のいずれかを使用する必要があります。アイデアは、スキーマにアクセスするための普遍的なルールがないということです。代わりに、リソース自体がそれを記述するスキーマを識別します。
典型的な例
要求
GET /api/companies
Accept: application/json
応答だから、
HTTP/1.1 200 OK
Content-Type: application/json; profile="/schema/companies"
{ ... }
、あなたのスキーマあなたが好きなように公開して自由に感じます。クライアントの実装を壊すことなく、必要に応じて変更することができます。新しいスキーマを指すように応答ヘッダーを変更するだけで、クライアントは動的に変更を処理できるはずです。
なぜ呼び出された場所に公開しませんか？
例えばschema/companies
schema/companies/10/employees
変更スキーマ
あなたのスキーマは、あなたが好きなようにエンドポイントの設定ができ
リソースURIで公開されている場合、従業員（たとえば）はクライアントに有効な企業ID（クライアントが認証されていると仮定していること）を知る必要があります。スキーマを保護する理由はありません。これは公開されたドキュメントで利用できるものです。 – davenewza
私の答えを編集しました –