よくある質問

JSON:API のバージョン番号の意味とは？

JSON:API は安定版 1.0 に到達したので、削除はせず、追加のみを行う戦略により、常に後方互換性を維持します。

バージョンは次の目的で管理されています。

仕様への追加変更を追跡できるようにするため。
特定の実装が潜在的にサポートする可能性のある機能を知るため。

HAL 仕様を使用しないのはなぜですか？

いくつかの理由があります。

HAL は子ドキュメントを再帰的に埋め込みますが、JSON:API はオブジェクトのグラフ全体をトップレベルでフラット化します。つまり、同じ「人」が異なる種類のオブジェクト（たとえば、投稿とコメントの両方を作成者）から参照されている場合、この形式により、ペイロードに各人物ドキュメントの単一の表現のみが存在することが保証されます。
同様に、JSON:API はリンクに ID を使用するため、複合レスポンスからのドキュメントをキャッシュし、後続のリクエストをローカルにまだ存在しないドキュメントのみに制限することができます。運が良ければ、HTTP リクエストを完全に排除することもできます。
HAL はシリアライゼーション形式ですが、ドキュメントの更新方法については何も述べていません。JSON:API は、既存のレコードを更新する方法（PATCH と JSON Patch に基づく）、およびこれらの更新が GET リクエストから返された複合ドキュメントとどのように相互作用するかを考慮しています。また、ドキュメントの作成と削除の方法、およびこれらの更新からの 200 および 204 レスポンスの意味についても説明しています。

要するに、JSON:API は、JSON を交換形式として使用する同様のアドホックなクライアントサーバーインターフェースを形式化しようとする試みです。これは、すでに見たドキュメントをキャッシュし、再度要求しない方法を知っているスマートクライアントでこれらの API を使用することに特に焦点を当てています。

これは、すでに多くのプロジェクトで使用されている実際のライブラリから抽出されたものであり、リクエスト/レスポンスの側面（HAL にはない）と交換形式自体の両方に情報を提供しています。

リソースのサポートされているアクションをどのように検出できますか？

クライアントが URI をリクエストするたびに、サーバーはレスポンスに Allow ヘッダーを含めて、リクエストされたリソースがサポートするメソッドを示すことができます。メソッドの検出をサポートするサーバーはこのヘッダーを含める必要があります。その後、クライアントは URI に HEAD リクエスト（または他のタイプのリクエスト）を送信して、サポートされているメソッドを検出できます。

たとえば、クライアントが HEAD /articles をリクエストすると、レスポンスには Allow: GET,POST ヘッダーが含まれる場合があります。これは、クライアントがコレクションを GET でき、新しいリソースを作成するために POST できることを示しています。

JSON:API は、リソースがサポートする非標準のアクションをアドバタイズし、詳細を説明する方法についてまだ検討中です。お気軽にディスカッションにご参加ください！

PUT はどこにありますか？

PUT を使用してリソースを部分的に更新する（つまり、状態の一部のみを変更する）ことは、HTTP 仕様では許可されていません。代わりに、PUT はリソースの状態を完全に置き換えることになっています。

「PUT メソッドは、ターゲットリソースの状態をリクエストメッセージペイロードの状態に作成または置き換えることをリクエストします。指定された表現の PUT が成功すると、同じターゲットリソースで後続の GET が実行されると、同等の表現が送信されることが示唆されます...」

したがって、部分的な更新の正しいメソッドは PATCH であり、JSON:API が使用しているものです。また、PATCH はリソースの完全な置き換えにも準拠して使用できるため、JSON:API はこれまでのところ PUT の動作を定義する必要がありませんでした。ただし、将来的には PUT セマンティクスを定義する可能性があります。

以前は、PATCH がまだ十分にサポートされていなかったため、多くの API が部分的な更新に PUT を使用していました。しかし、現在ではほとんどすべてのクライアントが PATCH をサポートしており、サポートしていないクライアントは簡単に回避できます。

JSON:API を記述する JSON スキーマはありますか？

はい、JSON スキーマ定義は https://jsonapi.dokyumento.jp/schema にあります。このスキーマは可能な限り制限的ですが、ドキュメント内で拡張できる柔軟性があります。検証では偽陰性は発生しませんが、柔軟性のために偽陽性が発生する可能性があります。

JSON スキーマ形式の詳細については、https://json-schema.dokyumento.jp をご覧ください。

リソースコレクションはなぜ ID でキーが指定されたセットではなく配列として返されるのですか？

JSON 配列は自然に順序付けられますが、セットはメンバー間の順序を指定するためにメタデータを必要とします。したがって、配列はデフォルトまたは指定された基準によるより自然なソートを可能にします。

JSON:API は、URI 構造、リソース URI に対する GET/POST/PATCH/DELETE のパラダイムに適合しないカスタムエンドポイントのルールなどについて、どのような立場をとっていますか？

JSON:API には URI 構造に関する要件はなく、実装は自由に好きな形式を使用できます。