Пагинация, фильтры и ошибки

Пагинация всегда keyset

Страницы нумеруются не номером, а курсором: в ответе приходит cursor, его надо передать в следующий запрос.

GET /api/v1/settlements
→ { "settlements": [...], "cursor": "1937..." }

GET /api/v1/settlements?cursor=1937...
→ { "settlements": [...], "cursor": null }

cursor: null означает, что список кончился.

Постраничного ?page=2 нет и не будет. Данные лежат по шардам, и OFFSET заставляет каждый шард прочитать и выбросить все строки до нужной — на десятой странице это десять тысяч прочитанных строк ради ста отданных. Курсор читает ровно то, что отдаёт.

Фильтры

Пустое значение — это отсутствие фильтра. ?q= означает «где угодно», а не «где название равно пустой строке».

Перечисления передаются именами: ?kind=cottage_village, а не ?kind=1. Числовое значение сервер тоже примет — оно лежит в базе, и человек, который подсмотрел его там, не должен получить непонятную ошибку, — но в документации и в схеме показаны только имена.

Ошибки

Тело ошибки валидации — стандартное для Laravel:

{
  "message": "The plot number field must not be greater than 20 characters.",
  "errors": {
    "plot_number": ["The plot number field must not be greater than 20 characters."]
  }
}

Лимиты запросов

По аккаунту, а не по адресу, — намеренно: ассистент работает на чьём-то ноутбуке за тем же NAT, что и тысяча других людей, и лимит по адресу заставил бы их делить бюджет.

Идентификаторы

Приходят и принимаются строками. Это снежинки — 64-битные числа, которые JavaScript округляет молча, а идентификатор, вернувшийся немного другим, — это объект, который больше не найти.