拡張機能とプロファイル

JSON:API の仕様では、拡張機能 を使用して、ベース仕様では提供されない新しい機能を定義する方法を規定しています。さらに、プロファイル を使用して、実装間で仕様の特定の使用方法を共有する方法を規定しています。

一般的に、拡張機能は、ベース仕様に含めるほど広く必要とされるわけではないが、一般的にコミュニティに標準があれば利益になると考えられる機能を標準化する方法を提供します。通常、そのような機能は、実装のために予約されている仕様の一部（たとえば、実装は独自のメンバーを attributes オブジェクトに追加できますが、リソース識別子に新しいメンバーを追加することはできません）のみを使用して実装するには難しすぎる、あるいは型破りすぎます。

一方、プロファイルは、実装のために予約されている仕様の一部（たとえば、ページングを処理する一般的な方法）のみを使用して、ベース仕様の一般的な使用方法を標準化する方法です。

拡張機能とプロファイルの大きな違いの 1 つは、拡張機能はクライアントとサーバーの両方で合意され、理解されている必要があるのに対し、プロファイルはクライアントまたはサーバーのどちらかが認識していない場合、安全に無視できるという点です。

いくつかの役立つ拡張機能とプロファイルは以下に示されています。ただし、拡張機能またはプロファイルは、以下に記載されている必要はありません。誰でも独自のドメインを使用して URI 向けに拡張機能またはプロファイルドキュメントを作成してホストできます。

JSON:API をアンチバイクシェディングツールとして約束を守るために、重要な違いや美的違いのために新しい拡張機能やプロファイルを作成するのではなく、共通の拡張機能やプロファイルの再利用、改善、共同作業を強く奨励します。

このページに記載されている拡張機能とプロファイルは、JSON:API 仕様の編集者によって確認されており、以下のように見なされています。

• ベース仕様と互換性がある
• 下位互換性を維持しながら進化できる
• 広範に役立つ

すべての拡張機能またはプロファイルがこのページに掲載できるわけでも、そうすべきでもありません。この一覧は可能な限り努力して維持されます。

拡張機能

• アトミック演算
  • URI: https://jsonapi.dokyumento.jp/ext/atomic
  • 名前空間: atomic
  • 説明: この拡張機能は、線形かつアトミックな方法で複数の「演算」を実行する方法を提供します。

プロファイル

• カーソルページング
  • URI: https://jsonapi.dokyumento.jp/profiles/ethanresnick/cursor-pagination
  • 説明: カーソルベースのページング（キーセットページングとも呼ばれます）は、「オフセット - 制限」ページングの多くの落とし穴を回避する一般的なページング戦略です。