[Enhancement]: Pagination metadata

[JerryNixon]

Proposal

Consider enhancing pagination to include page metadata?

Why?

Many APIs provide additional page information. All of this information is available to us.

Example: https://stapi.co/api/v2/rest/spacecraft/search

Example

{
    "page": {
        "pagingStrategy": "numeric|cursor" // `numeric` means $page, `cursor` means $after,
        "pageNumber": 0, // null when pagingStrategy == cursor
        "pageSize": 50, // reflects the global setting
        "totalPages": 29, // totalElements / pageSize
        "totalElements": 1443, // database count(*) with same filter
        "firstPage": true, // pageNumber == 0
        "lastPage": false // pageNumber == totalPages
    }
}

Configuration

{
  "runtime": {
    "pagination": {
      "max-page-size": 1000000,
      "default-page-size": 100,
      "include-metadata": <boolean; default: false> 
    }
  }
}

Ad hoc request

$page-metadata

Syntax

https://server/api/entity?$page-metadata=true

Rules

$page present	$after present	$page-metadata value	global setting	Is metadata included in the response payload?
🟩	🟥	🟩 true	n/a	included
🟥	🟩	🟩 true	n/a	included
🟥	🟥	🟩 true	n/a	-
n/a	n/a	🟥 false	n/a	-
🟩	🟩	🟨 missing	🟩 true	included
🟩	🟩	🟨 missing	🟩 true	included
🟥	🟩	🟨 missing	🟩 true	included
🟥	🟥	🟨 missing	🟩 true	-
🟩	🟩	🟨 missing	🟥 false	-
🟩	🟥	🟨 missing	🟥 false	-
🟥	🟩	🟨 missing	🟥 false	-
🟥	🟥	🟨 missing	🟥 false	-

As English

1. When the global setting is true:

   • Metadata is not returned if all three ($page, $after, and $page-metadata) are absent.
   • Metadata is returned if any of the following are true:
     • $page is used.
     • $after is used.
     • $page-metadata=true is explicitly used.

2. When the global setting is false:

   • Metadata is not returned if $page-metadata is not used or is set to false.
   • Metadata is only returned if $page-metadata=true is explicitly used.

3. Priority:

   • $page-metadata takes precedence when explicitly set, overriding the absence of $page or $after.

As C#

public static bool ShouldIncludeMetadata(
    int? pageValue, 
    string? afterValue, 
    bool? includeMetadata, 
    bool globalSetting = false)
{
    return includeMetadata switch
    {
        true when pageValue.HasValue => true, 
        true when !string.IsNullOrEmpty(afterValue) => true,
        null when pageValue.HasValue => globalSetting,
        null when !string.IsNullOrEmpty(afterValue) => globalSetting,
        _ => false
    };
}