Реєстр схем

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

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

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

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

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"
  }'

Активуйте її через POST /api/v1/projects/{projectId}/schemas/{eventTypeId}/versions/{versionId}/promote. Вона стає ACTIVE, а версія, яку вона замінює, — DEPRECATED.
Увімкніть валідацію для проєкту: задайте schemaValidationEnabled значення true й оберіть schemaValidationPolicy.

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

Статус	Що робить
`DRAFT`	Завантажена, не застосовується.
`ACTIVE`	Версія, за якою перевіряються події цього типу. Одна на тип події.
`DEPRECATED`	Зберігається для історії та порівняння, не застосовується. Активація нової версії переводить у цей стан ту, яку вона замінює; версію також можна застаріти напряму.

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

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

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

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

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

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

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

Що далі

Ендпоінти та підпискиШаблони типів подій і те, з чим збігається підписка.

Помилки та обмеженняЯк відхилену подію бачить відправник.

Довідник APIУсі запити й відповіді реєстру схем.