Перейти до вмісту
RailhookRailhookRailhook Docs
На сайт

Реєстр схем

Реєстр схем зберігає JSON Schema для кожного типу події в проєкті. Коли ви завантажуєте нову версію, Railhook порівнює її з попередньою й відхиляє зміни, які порушують обіцяну вами сумісність. Якщо ввімкнути валідацію, кожну подію перевірятимуть за активною версією одразу під час надходження, ще до збереження.

Додавання схеми

Section titled “Додавання схеми”

  1. Створіть тип події через POST /api/v1/projects/{projectId}/schemas. name — це тип події, наприклад order.completed.

  2. Завантажте версію. Вона отримує статус DRAFT і поки що не застосовується.

    Terminal window
    curl -X POST "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/schemas/$EVENT_TYPE_ID/versions" \
      -H "X-API-Key: $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "schemaJson": "{\"type\":\"object\",\"required\":[\"order_id\"],\"properties\":{\"order_id\":{\"type\":\"string\"}}}",
        "compatibilityMode": "BACKWARD"
      }'

  3. Зробіть її активною через POST /api/v1/projects/{projectId}/schemas/{eventTypeId}/versions/{versionId}/promote. Вона стає ACTIVE, а версія, яку вона замінює, — DEPRECATED.

  4. Увімкніть валідацію для проєкту: встановіть schemaValidationEnabled у true і виберіть schemaValidationPolicy.

Життєвий цикл версії

Section titled “Життєвий цикл версії”
Статус Що робить
DRAFT Завантажена, не застосовується.
ACTIVE Версія, за якою перевіряються події цього типу. Одна на тип події.
DEPRECATED Зберігається для історії та порівняння, не застосовується. Коли нова версія стає активною, та, яку вона замінює, переходить у цей статус; позначити версію застарілою можна й напряму.

Політики валідації

Section titled “Політики валідації”

Доки валідацію не ввімкнено в проєкті, вона не працює. Після ввімкнення подію, тип якої має версію ACTIVE, перевіряють за цією версією під час надходження. Події типу без активної версії не перевіряються.

schemaValidationPolicy Подія, що не відповідає схемі
WARN Приймається й доставляється, а помилки валідації відправник отримує у відповіді.
BLOCK Відхиляється з 400 і не зберігається, тож доставка не створюється.

Коли валідацію ввімкнено, новий для Railhook тип події потрапляє в реєстр зі схемою DRAFT, яку Railhook виводить із вмісту першої такої події. Перегляньте її і, якщо все правильно, зробіть активною.

Режими сумісності

Section titled “Режими сумісності”

Кожна версія має режим сумісності, і під час завантаження її перевіряють щодо попередньої версії. Версію, яка його порушує, Railhook відхиляє і не зберігає. Якщо режим не вказати, версія успадковує режим попередньої; для першої версії типово діє NONE.

Режим Що відхиляється
NONE Нічого. Жодних обіцянок і жодних перевірок.
BACKWARD Поле зі зміненим типом, нове обов’язкове поле, поле, що стало обов’язковим.
FORWARD Поле зі зміненим типом, видалене обов’язкове поле, поле, що перестало бути обов’язковим.
FULL Усе, що відхиляють BACKWARD і FORWARD.