ReSTful APIは主に他のシステムによって消費されるため、ページングデータを応答ヘッダーに配置します。ただし、一部のAPIコンシューマーは、応答ヘッダーに直接アクセスできない場合や、APIを介してUXを構築している場合があるため、JSON応答のメタデータを（オンデマンドで）取得する方法を提供することはプラスです。
実装には、デフォルトとして機械可読メタデータを含め、要求された場合は人間が読めるメタデータを含める必要があると思います。人間が読み取り可能なメタデータには、次のような、クエリパラメータを経由してオンデマンドで、好ましくは、必要であれば、すべての要求で返品することができinclude=metadataたりinclude_metadata=true。
特定のシナリオでは、各製品のURIをレコードに含めます。これにより、APIコンシューマーは個々の製品へのリンクを簡単に作成できます。また、ページング要求の制限に従って、いくつかの合理的な期待を設定します。ページサイズのデフォルト設定を実装して文書化することは、許容できる方法です。たとえば、GitHubのAPIは、デフォルトのページサイズを最大100の30レコードに設定し、さらにAPIをクエリできる回数のレート制限を設定します。APIにデフォルトのページサイズがある場合、クエリ文字列はページインデックスを指定するだけです。
人間が読めるシナリオでは、に移動する/products?page=5&per_page=20&include=metadataと、応答は次のようになります。
{
"_metadata":
{
"page": 5,
"per_page": 20,
"page_count": 20,
"total_count": 521,
"Links": [
{"self": "/products?page=5&per_page=20"},
{"first": "/products?page=0&per_page=20"},
{"previous": "/products?page=4&per_page=20"},
{"next": "/products?page=6&per_page=20"},
{"last": "/products?page=26&per_page=20"},
]
},
"records": [
{
"id": 1,
"name": "Widget #1",
"uri": "/products/1"
},
{
"id": 2,
"name": "Widget #2",
"uri": "/products/2"
},
{
"id": 3,
"name": "Widget #3",
"uri": "/products/3"
}
]
}
機械可読メタデータの場合、応答にリンクヘッダーを追加します。
Link: </products?page=5&perPage=20>;rel=self,</products?page=0&perPage=20>;rel=first,</products?page=4&perPage=20>;rel=previous,</products?page=6&perPage=20>;rel=next,</products?page=26&perPage=20>;rel=last
（リンクヘッダー値はurlencodedする必要があります）
...そして、選択した場合は、カスタムtotal-count応答ヘッダーもあります。
total-count: 521
人間中心のメタデータで明らかにされた他のページングデータは、リンクヘッダーによって現在のページとページあたりの数がわかり、配列内のレコード数をすばやく取得できるため、マシン中心のメタデータには不要な場合があります。 。したがって、私はおそらく合計数のヘッダーのみを作成します。後でいつでも気が変わって、メタデータを追加できます。
余談ですが、私が/indexあなたのURIから削除したことに気付くかもしれません。一般的に受け入れられている規則は、ReSTエンドポイントにコレクションを公開させることです。持つ/indexまでわずかエンドmuddiesで。
これらは、APIを使用/作成するときに私が持っていたいもののほんの一部です。お役に立てば幸いです。