Соглашения: запросы и ответы

Общие правила, применимые ко всем эндпоинтам API: форматы, даты, идентификаторы, пагинация.

Форматы данных

Большинство POST/PUT-эндпоинтов также принимают application/json-patch+json, text/json и application/*+json, но рекомендуется использовать обычный application/json.

Дата и время

Все временные значения — в формате ISO 8601.

Часовой пояс. Время бронирований трактуется в локальном часовом поясе ресторана. Часовой пояс ресторана доступен в GET /api/core/admin/account/me → restaurants[].timeZone. В значениях date-time смещение зоны, как правило, не указывается — отправляйте локальное время ресторана. При работе в другом часовом поясе конвертируйте время на своей стороне.

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

Типы ID в API смешанные — будьте внимательны:

restaurantId — числовой и присутствует почти во всех путях: /api/.../restaurants/{restaurantId}/.... Большинство остальных идентификаторов — строки (GUID).

Пагинация

Списочные эндпоинты с постраничной выдачей возвращают обёртку PagedResult:

{
  "results": [ /* элементы */ ],
  "count": 1234
}

Параметры постраничности и фильтрации (page, pageSize, search, диапазоны дат и т.п.) зависят от конкретного эндпоинта — смотрите его описание в соответствующем разделе.

Фильтрация по датам

Ряд списочных эндпоинтов требует диапазон дат. Например, список бронирований для внешних приложений (scope App) требует обязательный диапазон не более 60 дней (см. Бронирования).

Null и необязательные поля

• В ответах большинство полей nullable — проверяйте на null перед использованием.
• В запросах присылайте только нужные поля; отсутствующие трактуются как незаданные.
• Поля, помеченные в разделах как * (обязательные), должны присутствовать в запросе.

Идемпотентность и дубли

Отдельного заголовка идемпотентности (Idempotency-Key) спецификация не описывает. Чтобы избежать дублей при повторной отправке:

• Сохраняйте на своей стороне соответствие «ваш ID ↔ ID брони Hostme».
• Используйте поле source (и, где применимо, externalUserId) для маркировки происхождения записи.
• При сетевых ошибках сначала проверьте, не создалась ли запись (повторным GET), прежде чем повторять POST.

Заголовки