Visão Geral da API REST

O kikwi-management-rest expõe uma API REST de gestão/operação sobre um KikwiflowEngine já em execução — implantar definições, iniciar e consultar instâncias, completar tarefas externas, retentar incidentes, correlacionar eventos e acompanhar estatísticas. Ela é um cliente do motor como qualquer outro: não substitui KikwiflowEngine/QueryRepository para quem já está dentro do processo Java da aplicação (ver Tarefas Externas e Workers para o equivalente programático), é a superfície para quem opera de fora: um frontend de operação, um webhook de terceiros, um pipeline de deploy, um worker em outra linguagem.

Esta seção é a referência formal de cada endpoint. Para o "como" — desenhar telas, montar fluxos de integração — veja o Guia de Integração do Monitor, que usa esses mesmos endpoints para resolver casos de uso concretos.

Habilitando a API

Adicione kikwi-management-rest-spring-boot-starter ao classpath da aplicação Spring Boot que já hospeda o KikwiflowEngine (ver Instalação e Setup). Isso traz, via auto-configuração:

• Todos os controllers de comando (deploy, start, claim/complete, retry, correlate, ...) — registrados sempre que há um KikwiflowEngine no contexto.
• Todos os controllers de consulta (GET/POST /search, /pulse/*, /process-instances/{id}/events) — registrados sempre que há um QueryRepository no contexto.
• O tratador de exceções padrão (KikwiflowExceptionHandler), CORS e o resolver de IdentityContext.

Na prática os dois lados chegam juntos: o mesmo KikwiEngineRepository que a aplicação já precisa para o motor funcionar (kikwi-runtime-persistence-mongodb-spring-boot-starter em produção, kikwi-in-memory-addons em testes/demos) implementa QueryRepository — não há um starter de "API de busca" separado para instalar.

:::info Sobre kikwi-runtime-query-spring-boot-starter Esse starter existe para um caso diferente: embutir ExternalTaskQueryService (a API de consulta programática em Java) dentro do próprio processo da aplicação, sem passar por HTTP. Ele não registra nenhum endpoint REST — nenhum controller deste documento depende dele. Se seu objetivo é só consumir a API REST descrita aqui, ele é dispensável. :::

Path base

Todos os endpoints abaixo são relativos a kikwiflow.rest.base-path (padrão /kikwiflow/api/v1):

kikwiflow:
  rest:
    base-path: /kikwiflow/api/v1   # padrão
    cors:
      allowed-origins: []          # vazio = CORS desabilitado; preencha para liberar origins específicas

Ou seja, POST /process-instances neste documento é POST {base-path}/process-instances na sua aplicação — por padrão, POST /kikwiflow/api/v1/process-instances.

Mapa de recursos

Recurso	Endpoints	Referência
Definições de processo	deploy, buscar por id/key, listar, limpar cache	Definições de Processo
Instâncias de processo	iniciar, buscar, listar, contar, variáveis, encerrar, snapshot	Instâncias de Processo
Busca avançada de instâncias	POST /process-instances/search com filtros ricos	Busca Avançada
Tarefas externas	claim, unclaim, complete, buscar, contar	Tarefas Externas
Incidentes	buscar, retentar	Incidentes
Correlação de eventos	entregar uma correlação por chave (webhooks)	Correlação de Eventos
Histórico de eventos	timeline de eventos críticos de uma instância	Histórico de Eventos
Estatísticas (Pulse)	snapshot agregado + stream SSE	Estatísticas (Pulse)

Antes de integrar, vale ler Convenções, Autenticação e Erros — cobre o que é comum a todos os endpoints acima (formato de erro, paginação, como a API resolve identidade/tenant, e lacunas conhecidas do contrato atual).

Exemplo rápido

Implantar uma definição e iniciar uma instância:

curl -X POST http://localhost:8080/kikwiflow/api/v1/process-definitions \
  -H "Content-Type: application/json" \
  -d @onboarding-cliente.json

curl -X POST http://localhost:8080/kikwiflow/api/v1/process-instances \
  -H "Content-Type: application/json" \
  -d '{
        "processDefinitionKey": "onboarding-cliente",
        "businessKey": "cliente-42",
        "variables": { "email": { "name": "email", "value": "cliente@exemplo.com" } }
      }'

Note o deploy via API: por padrão ele está desabilitado (kikwiflow.security.deploy-enabled: false) — veja Definições de Processo antes de tentar o exemplo acima.