Pagination — Proposed Guide

Planned API — Reference Only

Pagination: Cursor pagination would let clients traverse expense collections without relying on page numbers that shift as new records arrive. The…

Overview

Cursor pagination would let clients traverse expense collections without relying on page numbers that shift as new records arrive. The proposed cursor is an opaque continuation value, not an editable offset.

Key concepts

Retain the original filter and sort order while following a cursor. An empty page and a missing next cursor convey different information; stop when continuation is absent.

Implementation considerations

Do not reuse a cursor across organizations or modified filters. Snapshot consistency and cursor expiry remain design decisions, not guaranteed behavior.

Proposed API behavior

GET /v1/expenses is an illustrative design for this topic. Path and field names may change before implementation. Access would require an authorized organization context and operation-specific permission; no public API or authorization grant is available here.

Illustrative query parameters
Name	Type	Description
limit	integer	Requested collection size. This example is not a promised service limit.
cursor	string	Opaque fictional continuation value; retain the original filters when following it.
sort	string	Illustrative ordering expression with a stable identifier tie-breaker.

Static example requests

Proposed, non-executing request examples

# Proposed request text only; this reserved host is not a live API.
curl -X GET 'https://api.remizen.example/v1/expenses?limit=25&cursor=cursor_example_123&sort=-incurred_on%2Cid' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Fictional response example

200 (proposed example)Static response fixture

Fictional documentation data only. No request was sent, record created, review performed, payment initiated or provider connection activated.

JSON

{
  "data": [
    {
      "id": "exp_example_123",
      "organization_id": "org_example_123",
      "merchant": "Example Office Supply",
      "amount_minor": 12550,
      "currency": "USD",
      "status": "draft"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_example_123",
    "reference_only": true
  }
}

Illustrative error case

Review this failure case in context: Do not reuse a cursor across organizations or modified filters. Snapshot consistency and cursor expiry remain design decisions, not guaranteed behavior.

422 (illustrative; final error contracts are undecided)Proposed error fixture

Synthetic diagnostic example. Human-readable messages must not be used as stable programmatic contracts.

JSON

{
  "error": {
    "code": "validation_error",
    "message": "The proposed pagination operation requires review of its input or authorization.",
    "request_id": "req_example_123"
  }
}

Proposed data types

Illustrative field dictionary
Name	Type	Description
limit	integer	Requested collection size. This example is not a promised service limit.
cursor	string	Opaque fictional continuation value; retain the original filters when following it.
sort	string	Illustrative ordering expression with a stable identifier tie-breaker.

Response Structure

Getting Started

Filtering