Управление флагами

Контроллер app/КонтролАПИ.os, префикс /api. Все эндпоинты требуют аутентификации.

winow маршрутизирует только по пути, поэтому метод запроса проверяется в контроллере вручную: неподдержанный метод даёт 405.

Список флагов

GET /api/flags?env=dev

Отдаёт все флаги вместе с их настройкой в указанном окружении.

Ответ 200

{
  "окружение": "dev",
  "флаги": [
    {
      "ключ": "new-checkout",
      "имя": "Новая корзина",
      "описание": "",
      "тип": "boolean",
      "варианты": { "вкл": true, "выкл": false },
      "настройка": {
        "включен": true,
        "вариантПоУмолчанию": "вкл",
        "процентВыкатки": 25,
        "правила": []
      }
    }
  ]
}

Поле настройка может быть null, если у флага нет записи для этого окружения.

Создать флаг

POST /api/flags

Тело

Поле	Тип	Назначение
ключ	string	Идентификатор флага
имя	string	Отображаемое имя
описание	string	Необязательное пояснение
тип	string	boolean, string, number или object
варианты	object	Имя варианта → значение

Ответ 201 - созданный флаг целиком.

Публикуется событие com.oneflag.flag.created.

curl -X POST http://localhost:3333/api/flags \
  -H "Authorization: Bearer local-sdk-key" \
  -H "Content-Type: application/json" \
  -d '{"ключ":"new-checkout","имя":"Новая корзина","тип":"boolean"}'

Один флаг

GET /api/flags/{ключ}

Ответ 200 - описание флага со всеми окружениями. Несуществующий ключ - 404.

Изменить настройку

PATCH /api/flags/{ключ}?env=dev
PUT   /api/flags/{ключ}?env=dev

Меняет настройку флага в одном окружении. Оба метода делают одно и то же.

Тело

Поле	Тип	Назначение
включен	boolean	Флаг включён в окружении
вариантПоУмолчанию	string	Вариант, когда правила не сработали
процентВыкатки	number	Доля аудитории, 0..100
правила	array	Правила таргетинга

Ответ 200 - обновлённая настройка.

Публикуется событие com.oneflag.flag.changed с полями включен, вариантПоУмолчанию и процентВыкатки - именно на него реагируют SDK и открытые дашборды.

curl -X PATCH "http://localhost:3333/api/flags/new-checkout?env=prod" \
  -H "Authorization: Bearer local-sdk-key" \
  -H "Content-Type: application/json" \
  -d '{"включен":true,"процентВыкатки":25}'

Удалить флаг

DELETE /api/flags/{ключ}

Ответ 204 без тела. Несуществующий ключ - 404.

Публикуется событие com.oneflag.flag.deleted.

Окружения

GET /api/environments

Ответ 200 - массив окружений с ключом, именем и порядком отображения. Состав задаётся переменной ONEFLAG_ENVIRONMENTS.

Аудит

GET /api/audit?limit=50

Журнал изменений, свежие записи первыми. По умолчанию limit равен 50; сколько записей хранится вообще, задаёт ONEFLAG_AUDIT_LIMIT.

Ответ 200 - массив записей. Каждая содержит событие CloudEvents 1.0 целиком плюс колонки для отбора.

Тип события	Когда
com.oneflag.flag.created	Флаг создан
com.oneflag.flag.changed	Настройка флага в окружении изменена
com.oneflag.flag.deleted	Флаг удалён