Sorting lists
Four list endpoints take ?sort= and ?order=. Each keeps its existing order
as the default, so nothing changes for a caller who does not ask.
| Endpoint | Sortable fields | Default |
|---|---|---|
GET /v1/messages |
queued_at, updated_at |
queued_at desc |
GET /v1/domains |
domain, created_at, verified_at |
created_at desc |
GET /v1/templates |
name, created_at, updated_at |
name asc |
GET /v1/api-keys |
label, created_at, last_used_at, expires_at |
created_at desc |
curl "https://api.lockally.com/v1/templates?sort=name&order=desc" \
-H "Authorization: Bearer $LOCKALLY_API_KEY"
order is asc or desc. Omit it and you get the default direction for the
default field, or ascending for any other field, because ?sort=label
meaning descending would surprise everybody.
An unknown field is a 400, not a fallback
{
"title": "Invalid sort field",
"detail": "`sort` must be one of: created_at, expires_at, label, last_used_at. Got \"name\".",
"code": "invalid_sort_field"
}
Silently ignoring it is the failure this avoids: ?sort=recipient appearing to
work while changing nothing, and the afternoon spent wondering why.
Why the sortable set is this small
On /v1/messages, the offered fields are exactly the indexed ones. An
unindexed sort there is a sequential scan of an account’s whole send history on
every request, and the first account it hurts is the one with the most
messages. status and sender are deliberately absent: both are already
filters, which is cheaper and more useful than ordering by them.
The other three lists hold tens of rows per account, so sorting them is free and every column is offered. No index was added for those, and adding one would cost more than it saves.
The order is always total
Every clause is tie-broken on id. ORDER BY queued_at DESC alone has no
defined order between rows sharing a timestamp, so two pages can repeat one
row and omit another, and nothing reports it. Postgres is free to return equal
rows in any order and will change its mind under a different query plan.
Endpoints not in this set
Every other list keeps its fixed order. That is a gap rather than a decision, and it is named here rather than papered over: the four above are the ones where ordering is actually asked for, and a pass that quietly covered half the API while implying all of it would be worse than a short list.