Skip to main content

Auth, Payloads, Pagination & Versioning

Stable clients with rate limits, idempotency, and forward-compatible payloads.

C
Written by Catalin Fetean
Updated over 2 weeks ago

Audience: Developers
​Prerequisites: API base URL; session cookie storage
​Outcomes: Predictable requests; clean upgrades

Authenticate & persist session

curl -X POST $API_BASE/api/auth/login \ -H 'Content-Type: application/json' \ -d '{"email":"[email protected]","password":"••••••"}' \ -c cookies.txt curl -X GET $API_BASE/api/auth/session -b cookies.txt

Request rules

  • Content-Type: application/json

  • Amounts in minor units

  • Include your own reference (idempotency)

Rate limits (default)

  • 100 req/min per org (plan-dependent)

  • On 429: exponential backoff with jitter; reuse idempotency key

Pagination & delta sync

  • Lists: ?limit=50&nextCursor=...

  • Deltas: ?updatedSince=2025-01-01T00:00:00Z

  • Large accounts: initial REST backfill, then rely on webhooks for changes

Data contracts & forward-compatibility

  • Validate bodies against JSON Schema/OpenAPI

  • Accept unknown fields (forward compatible), validate required strictly

Versioning & deprecation

  • Prefer additive changes; breaking → /v2 or header X-TradeOS-Version

  • Publish changelog + migration guides

QA checklist

  • Client tolerates added fields without breaking

  • Pagination cursors resume correctly after retry

Runbook: “Backfill needed”

  • Run initial sync via updatedSince + cursors, then enable webhooks.

Did this answer your question?