Sorting Pagination and Sparse Fieldsets

Sorting, Pagination, and Sparse Fieldsets

• Applies to: Flask and FastAPI
• Best sources: safrs/request.py, safrs/jsonapi_context.py, tests/test_fastapi_parity_semantics.py
• Related pages: Filtering, Content Types and Errors, Configuration Reference

Sorting

Use sort= with one or more fields:

• sort=name
• sort=name,-created

The FastAPI parity tests also assert multi-field sorting and the default fallback sort order by id when no explicit sort is provided.

Offset / limit pagination

Use:

• page[offset]
• page[limit]

Example:

GET /Orders?page[offset]=20&page[limit]=10

Number / size pagination

SAFRS also supports:

• page[number]
• page[size]

These are translated to offset/limit internally.

Example:

GET /Orders?page[number]=2&page[size]=5

That means “page 2 with 5 items per page”, which starts at offset 5.

Relationship pagination

Relationship collections support relationship-scoped page parameters:

• page[items][limit]
• page[items][offset]
• page[items][number]
• page[items][size]

The exact relationship name replaces items.

Sparse fieldsets

Use fields[TYPE]=... to restrict the serialized attributes for a type:

GET /Order?fields[Order]=Id,ShipName

exclude

SAFRS also recognizes exclude for excluding named relationships from include-heavy responses.

Example:

GET /Order?include=Customer,Employee&exclude=Orders

Config interaction

Pagination behavior is shaped by configuration such as:

• DEFAULT_PAGE_LIMIT
• MAX_PAGE_LIMIT
• MAX_PAGE_OFFSET

See Configuration Reference.