Skip to content
Last updated

Pagination and versioning

Read a long list one page at a time

A list route gives you one page at a time. Ask for a page size with limit. It is 25 if you do not send it, and it can be 1 to 100.

The page comes back in data:

{
  "ok": true,
  "data": {
    "items": [],
    "nextCursor": "<cursor>",
    "total": 120
  }
}
  • items is this page.
  • nextCursor gets the next page. Send it back as cursor. When it is null, you have the last page.
  • total is how many there are in all. It is null when the count is not known. A null total does not mean zero.
curl -H "Authorization: Bearer $HRC_LEDGER_KEY" \
  "https://hrcledger.com/api/v1/lists?limit=25&cursor=<cursor>"

A cursor is only for the list that made it. Do not build or change one by hand.

The contract and organization searches

GET /api/v1/contracts and GET /api/v1/market/orgs came first and use page numbers instead. Send page (it starts at 1) and limit. The answer has page and total next to data.

The version is in the address

Every route starts with /api/v1. The v1 is the version.

We do not break v1. These changes can happen in v1, so write your code to allow them:

  • a new route,
  • a new field in an answer,
  • a new optional parameter,
  • a new error code.

These changes would break your code, so they only come with a new version, such as /api/v2:

  • a field taken out of an answer,
  • a field whose type changes,
  • a parameter that becomes required,
  • a route taken away.

Every change to the contract is in the Changelog, with its date.

Errors

Changelog