Sorting — Proposed Guide

Planned API — Reference Only

Sorting: Stable sorting determines the order of a collection and supports reliable continuation. The proposed sort expression uses a leading minus sign…

Overview

Stable sorting determines the order of a collection and supports reliable continuation. The proposed sort expression uses a leading minus sign for descending order and an identifier as a final tie-breaker.

Key concepts

Order by a documented timestamp or business date, then by a stable id when values match. A display label is unsuitable as the only ordering key because it can change.

Implementation considerations

Sorting and cursor generation must agree. A future server should reject unsupported combinations rather than returning a partially ordered result.

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
sort	string	Illustrative ordering expression with a stable identifier tie-breaker.
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.

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?sort=-incurred_on%2Cid&limit=25&cursor=cursor_example_123' \
  -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: Sorting and cursor generation must agree. A future server should reject unsupported combinations rather than returning a partially ordered result.

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 sorting operation requires review of its input or authorization.",
    "request_id": "req_example_123"
  }
}

Proposed data types

Illustrative field dictionary
Name	Type	Description
sort	string	Illustrative ordering expression with a stable identifier tie-breaker.
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.

Filtering

Getting Started

Error Handling