Conectando a sua própria API

O Flowker traz conectores para os serviços do catálogo dele. Quando o serviço que você quer chamar é seu — uma API interna, a API de um parceiro, qualquer uma com um documento OpenAPI publicado — você sobe esse documento e um node de workflow chama as operações dele direto. Você faz isso uma vez por documento: sobe o documento, cria uma configuração de provider que aponta para ele e depois endereça uma operação a partir de cada node que chama o serviço.

Antes de começar

O documento OpenAPI 3.x do seu serviço como arquivo, com no máximo 8 MiB, declarando pelo menos uma operação.
As credenciais que o seu serviço exige e o método de autenticação que ele espera. Veja Autenticação para os métodos que o Flowker aceita.
Uma implantação cujo registro de schemas tenha armazenamento de blobs configurado. SCHEMA_REGISTRY_S3_BUCKET guarda os documentos OpenAPI que você sobe — veja Variáveis de ambiente do Flowker.
Um workflow em estado draft para editar. Um workflow ativo fica bloqueado, então chame Mover o workflow para draft primeiro e ative-o de novo depois.

O Lerian Console cobre o mesmo caminho. Providers → + New Provider → Add your own API seleciona um documento já enviado e define a URL base e a autenticação — veja Adicionando um provider.

Passo 1: Suba o documento OpenAPI

Envie o arquivo

Chame Subir um schema OpenAPI como multipart/form-data com três partes: o file, um name e uma version.

curl -X POST https://seu-host-flowker/v1/openapi-schemas \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@acme-kyc.json" \
  -F "name=acme-kyc" \
  -F "version=v1.0.0"

Guarde o id

A resposta 201 descreve o que o Flowker leu do arquivo. O id dela é o valor que cada passo seguinte referencia.

Campo	O que ele diz
`id`	O identificador do documento. Uma configuração de provider e um trigger de webhook apontam para ele.
`name`, `version`	O par que você enviou.
`title`	O `info.title` do documento.
`openapiVersion`	A versão `openapi` que o documento declara.
`operationCount`	Quantas operações de caminho e método o documento declara.
`contentHash`, `byteSize`	O digest e o tamanho do arquivo armazenado.
`createdBy`, `createdAt`	Quem subiu o documento e quando.

Por qual chave um documento armazenado é identificado

name e version são escolha sua, com até 255 caracteres cada. O par é único no seu tenant: subir de novo o mesmo name e a mesma version responde FLK-0812. O id que o Flowker devolve é um UUID novo em cada envio, e é ele que todo o resto referencia — nunca o nome nem a versão. O Flowker analisa o arquivo antes de armazená-lo. Um arquivo que não é um documento OpenAPI 3.x, ou que não declara nenhuma operação, responde FLK-0900. Um arquivo com mais de 8 MiB responde FLK-0901. Os documentos que você sobe são só seus. Um documento fica visível apenas para o tenant que o subiu, e um id de outro tenant nunca é resolvido.

Passo 2: Veja as operações que você pode chamar

Liste o que você tem armazenado

Listar schemas OpenAPI devolve os seus documentos apenas como metadados, sem o conteúdo deles. A rota é paginada: limit, cursor, sortBy e sortOrder, e a resposta traz nextCursor e hasMore.

Veja as operações de um documento

Obter um schema OpenAPI devolve os mesmos metadados mais content — o arquivo armazenado — e operations, uma entrada por operação que o documento declara.

Campo	O que ele diz
`path`	O caminho da operação, exatamente como o documento o escreve, como `/v1/checks`.
`method`	O método HTTP da operação.
`operationId`	O `operationId` do documento, quando ele declara um.
`hasRequest`	Se a operação declara um corpo de requisição JSON.
`hasResponse`	Se a operação declara uma resposta de sucesso JSON.

Copie o path e o method da operação que você quer. O Passo 4 coloca os dois no node.

Veja os nomes de campo de uma operação

Derivar o schema de uma operação recebe um path e um method e devolve inputSchema — o corpo da requisição da operação — e outputSchema — a resposta de sucesso dela. Devolve também params, uma entrada por parâmetro que a operação declara, cada uma com o name dela, a localização in e se é required.Esses são os nomes de campo que você escreve como target e como source dos seus mapeamentos no Passo 4. Os dois parâmetros de consulta são obrigatórios, e o method não diferencia maiúsculas e precisa ser um de GET, PUT, POST, DELETE, OPTIONS, HEAD, PATCH ou TRACE; um path ausente ou um method não reconhecido respondem FLK-0304. Um caminho e um método que o documento não declara respondem FLK-0902.

Passo 3: Aponte uma configuração de provider para o documento

Chame Criar uma configuração de provider com kind em external_openapi. Esse kind é a conexão que traz o seu próprio OpenAPI: ela referencia o documento que você subiu em vez de um provider do catálogo.

Campo	Obrigatório	Descrição
`kind`	Sim	`"external_openapi"`. Você escolhe o kind ao criar a configuração, e ela permanece com o kind com que foi criada.
`providerId`	Não	Omita: esta conexão aponta para o seu próprio documento, não para um provider do catálogo. Uma leitura da configuração então devolve o id reservado `external.openapi`.
`name`	Sim	Um nome para esta conexão, de 1 a 100 caracteres.
`config.openapi_schema_id`	Sim	O `id` do Passo 1. Ele precisa nomear um documento do seu tenant.
`config.base_url`	Não	O esquema, o host e o prefixo de caminho para onde o Flowker envia as requisições. Omita para usar a primeira entrada `servers` utilizável do documento.
`config.auth`	Não	Um bloco de autenticação `{ type, config }`, no mesmo formato que qualquer configuração de provider usa. Veja Autenticação para cada tipo e os campos dele. Omita para um serviço que não exige autenticação.
`allowedHosts`	Não	Os hosts que esta configuração pode chamar. Omita, ou envie uma lista vazia, para aceitar qualquer host público.
`allowedPrivateHosts`	Não	Hosts privados nomeados que esta configuração pode alcançar. Endereços de metadados de nuvem e link-local continuam bloqueados.
`schemaBindings`	Não	Os documentos armazenados aos quais esta configuração se vincula. Veja Vincule o documento.
`description`	Não	Texto livre, até 500 caracteres.
`metadata`	Não	Os seus próprios pares chave-valor.

Para onde vai a credencial

O segredo dentro de config.auth é somente de escrita. O Flowker o envia para o seu backend de segredos, o remove do documento de configuração antes de salvar o documento e o resolve a partir do backend no momento da execução. Nenhuma rota de configuração de provider o devolve. Qualquer outra coisa que você coloque no documento de configuração fica armazenada com a configuração, e uma leitura pode devolvê-la — então coloque cada credencial em config.auth. Para rotacionar um segredo depois, envie o valor novo em uma atualização. Para manter o atual, omita o campo ou envie-o em branco enquanto auth.type não mudar — veja Autenticação.

Onde as listas de hosts permitidos são definidas

As duas listas pertencem a esta chamada de criação e, depois, a Atualizar uma configuração de provider. allowedHosts nomeia os hosts que cada node que chama por meio desta configuração pode alcançar; o Flowker verifica contra ela a URL da requisição e cada salto de redirecionamento em tempo de execução. Uma entrada com ponto inicial casa com subdomínios, então .acme-kyc.example.com casa com api.acme-kyc.example.com. As entradas são apenas nomes de host, sem literal de IP, sem curinga e sem porta. allowedPrivateHosts é a lista companheira para um serviço que vive em uma rede privada. Uma entrada permite que esta configuração alcance um host que resolve para um endereço privado ou de loopback, que o Flowker bloqueia por padrão. Endereços de metadados de nuvem e link-local continuam bloqueados, e nenhuma entrada os alcança.

Vincule o documento

Adicione uma entrada schemaBindings para o documento que você referenciou. Cada entrada nomeia um documento armazenado: type é "openapi", schemaId é o mesmo id que você colocou em config.openapi_schema_id, e o array opcional operations restringe o vínculo às operações que os seus workflows realmente chamam. O vínculo é o que torna visíveis os dependentes do documento. Com ele, Listar os recursos que referenciam um schema OpenAPI informa esta configuração, e uma exclusão do documento é recusada enquanto a configuração estiver ativa — veja Removendo um documento. O Flowker resolve cada vínculo quando você salva. Um schemaId que não nomeia nenhum documento do seu tenant responde FLK-0942, e uma entrada de operations que o documento não declara responde FLK-0943, cada um nomeando a entrada que falhou. Uma entrada malformada — um type desconhecido, um schemaId que não é UUID, operations em um vínculo que não é openapi, ou uma operação sem caminho nem método — responde FLK-0293.

Exemplo de requisição

POST /v1/provider-configurations

{
  "name": "Acme KYC production",
  "description": "Production KYC checks",
  "kind": "external_openapi",
  "config": {
    "openapi_schema_id": "018f3e2a-1c4d-7b9e-a1b2-c3d4e5f6a7b8",
    "base_url": "https://api.acme-kyc.example.com",
    "auth": {
      "type": "api_key",
      "config": {
        "key": "sk-live-xxx",
        "header_name": "X-API-Key",
        "location": "header"
      }
    }
  },
  "allowedHosts": ["api.acme-kyc.example.com"],
  "schemaBindings": [
    {
      "type": "openapi",
      "schemaId": "018f3e2a-1c4d-7b9e-a1b2-c3d4e5f6a7b8",
      "operations": [
        { "path": "/v1/checks", "method": "POST" },
        { "path": "/v1/checks/{checkId}", "method": "GET" }
      ]
    }
  ]
}

A resposta devolve o id da nova configuração. Guarde-o — o Passo 4 o coloca no providerConfigId de cada node que chama este serviço.

O Flowker verifica a configuração antes de armazená-la. Um config sem openapi_schema_id, ou cujo valor não é um UUID, responde FLK-0946. Um id que não nomeia nenhum documento do seu tenant responde FLK-0947. Um bloco config.auth que o Flowker não consegue ler — um tipo desconhecido, ou um tipo sem um dos campos obrigatórios dele — responde FLK-0948. Nenhuma chamada de rede acontece nesse ponto.

Passo 4: Enderece uma operação a partir de um node de workflow

Um node executor nomeia uma operação do documento com dois campos no data dele, junto ao providerConfigId da configuração do Passo 3.

Campo	Obrigatório	Descrição
`providerConfigId`	Sim	O UUID da configuração de provider que aponta para o documento.
`operation_path`	Sim	O caminho da operação, exatamente como o documento o escreve, incluindo os templates de parâmetro `{...}`.
`operation_method`	Sim	O método HTTP da operação. A correspondência não diferencia maiúsculas.
`inputMapping`	Não	Move valores do contexto do workflow para a requisição. Cada `target` é um caminho do corpo da requisição, ou o nome de um parâmetro.
`outputMapping`	Não	Move valores para fora da resposta, para os nodes seguintes lerem.

Não envie executorId em um node assim. O Flowker resolve a configuração de provider, reconhece o kind e preenche o campo por você antes de validar o workflow. Todos os outros campos do node se comportam como descreve Referenciar a configuração de provider a partir de um node de workflow.

Como a requisição é montada

O Flowker lê a operação do documento armazenado em tempo de execução e monta a requisição a partir dela:

O destino é config.base_url quando a configuração o define e, na falta dele, a primeira entrada servers utilizável do documento, unida com operation_path.
Um parâmetro path pega o valor dele primeiro nos dados resolvidos do node e, em segundo lugar, no corpo da requisição. Todo parâmetro path precisa de um valor.
Um parâmetro query ou header é resolvido do mesmo jeito, e fica de fora quando nenhum valor é encontrado.
O corpo da requisição é o que o seu inputMapping monta. Escreva cada target exatamente como o schema de requisição da operação o nomeia: não há objeto envolvente nem prefixo a acrescentar. Trabalhando com os dados da requisição e da resposta cobre os mapeamentos e as transformações por completo.

Exemplo — um workflow que chama duas operações do documento

POST /v1/workflows

{
  "name": "kyc-check",
  "description": "Opens a KYC check on the Acme API and records the result.",
  "nodes": [
    {
      "id": "kyc-received",
      "type": "trigger",
      "name": "KYC request received",
      "position": { "x": 0, "y": 0 },
      "data": {
        "triggerType": "webhook",
        "path": "kyc/requested",
        "method": "POST",
        "input_contract": "open",
        "format": "json"
      }
    },
    {
      "id": "open-check",
      "type": "executor",
      "name": "Open KYC check",
      "position": { "x": 200, "y": 0 },
      "data": {
        "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
        "operation_path": "/v1/checks",
        "operation_method": "POST",
        "inputMapping": [
          { "source": "workflow.documentNumber", "target": "documentNumber" },
          { "source": "workflow.fullName", "target": "fullName" }
        ],
        "outputMapping": [
          { "source": "body.checkId", "target": "checkId" },
          { "source": "body.status", "target": "status" }
        ]
      }
    },
    {
      "id": "record-check",
      "type": "action",
      "name": "Record the check",
      "position": { "x": 400, "y": 0 },
      "data": {
        "actionType": "set_output",
        "output": {
          "checkId": "${open-check.checkId}",
          "status": "${open-check.status}"
        }
      }
    }
  ],
  "edges": [
    { "id": "e1", "source": "kyc-received", "target": "open-check" },
    { "id": "e2", "source": "open-check", "target": "record-check" }
  ]
}

O node open-check envia POST https://api.acme-kyc.example.com/v1/checks com o corpo que o inputMapping dele montou. O outputMapping dele extrai dois campos da resposta, então o node seguinte lê ${open-check.checkId}.Um node que chama GET /v1/checks/{checkId} lê o parâmetro do mesmo escopo do node. Mapeie um valor para checkId e o Flowker o substitui no caminho.

Um trigger de webhook pode validar o payload de entrada contra uma operação do mesmo documento. Ponha input_contract em "openapi" e dê ao trigger openapi_schema_id, operation_path e operation_method — veja Configurando um trigger de webhook.

Passo 5: Execute e confirme que funcionou

Ative o workflow

Chame Ativar um workflow. A ativação registra a rota de webhook e resolve o que o contrato do trigger referencia.

Execute

Chame Executar um workflow com um cabeçalho Idempotency-Key novo, ou envie uma requisição para a rota de webhook.

Leia os resultados dos passos

Um node que chegou ao seu serviço registra a resposta sob o id dele. Com um outputMapping, os nomes mapeados ficam direto sob esse id — open-check.checkId. Sem outputMapping, a saída do node mantém o envelope da resposta, então o corpo da resposta fica um nível abaixo, sob body.

Publicando uma nova versão do seu documento

Um documento armazenado não muda. Para publicar uma revisão, suba o arquivo de novo com uma version nova; isso lhe dá um segundo documento armazenado com o id próprio dele. Nada troca por conta própria. Toda referência é por id, então um workflow que já está em execução continua chamando o documento que ele referencia. Para movê-lo, envie o config da configuração de provider com o novo openapi_schema_id por Atualizar uma configuração de provider. O config substitui o mapa armazenado em vez de se mesclar a ele, então inclua base_url e auth na mesma chamada. O Flowker revalida o id novo contra o seu tenant, e responde FLK-0947 quando ele não é resolvido. Consulte Listar os recursos que referenciam um schema OpenAPI sobre o documento anterior antes de retirá-lo — a rota nomeia tudo o que ainda aponta para ele.

Versões de especificação dos serviços do catálogo

Os serviços do próprio catálogo do Flowker são resolvidos contra um registro compartilhado de especificações publicadas, separado. Três operações o gerenciam. Elas nunca tocam um documento que você subiu no Passo 1.

Operação	O que ela faz
Listar versões de especificação OpenAPI	Lista em `versions` as versões publicadas da especificação de um serviço, e informa em `pinnedVersion` a que o seu tenant fixou. `pinnedVersion` fica vazio quando o seu tenant não fixou nenhuma.
Fixar uma versão de especificação OpenAPI	Seleciona a versão contra a qual o seu tenant é resolvido para aquele serviço. A operação é idempotente: fixar de novo substitui a versão no lugar. Uma requisição sem o serviço ou sem a versão responde `FLK-0801`.
Subir uma versão de especificação OpenAPI	Publica uma versão da especificação de um serviço, para todos os tenants. As versões são imutáveis: um par de `service` e `version` que já existe responde `FLK-0803`. Quem chama precisa da permissão `create` sobre o recurso `catalog`.

A fixação é por tenant. Publicar uma versão não muda nada para um tenant até que esse tenant a fixe, então um envio novo nunca move um workflow em execução para outra especificação. O Flowker lê a versão que você fixou quando informa os schemas dos executors daquele serviço no catálogo, então Obter um executor do catálogo descreve a versão que você escolheu.

Removendo um documento

Verifique o que quebraria

Listar os recursos que referenciam um schema OpenAPI devolve dois grupos, providerConfigurations e workflows. Os dois estão sempre presentes, e cada entrada carrega um id, um name e um status. Uma entrada com status ativo bloqueia a exclusão; uma inativa apenas avisa.

Exclua o documento

Excluir um schema OpenAPI responde conforme o que ainda referencia o documento:

Resultado	O que significa
`204 No Content`	Nada referenciava o documento. Ele foi removido.
`200 OK`	Só referentes inativos o mantinham — um workflow em draft ou inativo, ou uma configuração de provider desabilitada. O documento foi removido, e o corpo nomeia cada um sob `warnings` e `providerConfigurationWarnings`.
`409` com `FLK-0945`	Uma configuração de provider ativa vincula o documento. Nada é excluído, e o corpo lista as configurações de provider e os workflows que o referenciam.
`409` com `FLK-0936`	Um workflow ativo referencia o documento a partir de um trigger de webhook. Nada é excluído.

Para liberar um bloqueio, desabilite a configuração de provider com Desabilitar configuração de provider, ou mova o workflow para draft com Mover o workflow para draft, e exclua o documento de novo.

O que pode dar errado

Sintoma	Causa	Correção
O envio é recusado mesmo que o arquivo abra no seu editor.	O documento declara uma versão `openapi` fora da série 3.x, ou não declara nenhuma operação.	Confira o campo `openapi` e o objeto `paths`, e suba o arquivo de novo.
A chamada de criação informa que o id do schema é desconhecido.	O id pertence a outro tenant, ou o documento foi excluído.	Chame Listar schemas OpenAPI e pegue o id da resposta.
O workflow é recusado com `FLK-0150`.	O `providerConfigId` do node nomeia uma configuração que não existe, ou uma desabilitada.	Confirme o UUID do node, e habilite a configuração com Habilitar configuração de provider.
O node falha sem chegar ao seu serviço.	A operação não está no documento, ou nenhuma URL base é resolvida.	Compare `operation_path` e `operation_method` com a lista `operations` do Passo 2, e defina `config.base_url` quando o documento não declara nenhuma entrada `servers`.
O serviço responde que falta um campo obrigatório.	Um `target` de mapeamento não casa com o schema de requisição da operação.	Leia `inputSchema` em Derivar o schema de uma operação e escreva cada target exatamente como ele aparece ali.
O serviço nunca é alcançado e o passo informa uma URL recusada.	`allowedHosts` não cobre o host de destino.	Acrescente o host a `allowedHosts` na configuração de provider.

Código de erro	Quando	O que significa
`FLK-0150`	Criar ou ativar o workflow	O `providerConfigId` do node nomeia uma configuração que não existe, ou uma que não está ativa.
`FLK-0812`	Envio	Já existe um documento com este `name` e esta `version`. Escolha outra versão.
`FLK-0900`	Envio	O arquivo não é analisado como documento OpenAPI 3.x, ou não declara nenhuma operação.
`FLK-0901`	Envio	O arquivo passa de 8 MiB.
`FLK-0811`	Leitura, derivação, exclusão	O id do documento não é resolvido para o seu tenant.
`FLK-0902`	Derivar o schema de uma operação	O documento não declara nenhuma operação com aquele caminho e método.
`FLK-0304`	Derivar o schema de uma operação	O parâmetro de consulta `path` está ausente, ou `method` está ausente ou não é um método HTTP.
`FLK-0946`	Criar ou atualizar a configuração de provider	Falta `config.openapi_schema_id`, ou o valor não é um UUID.
`FLK-0947`	Criar ou atualizar a configuração de provider, e em tempo de execução	O documento referenciado não existe no seu tenant.
`FLK-0948`	Criar ou atualizar a configuração de provider	O bloco `config.auth` está malformado.
`FLK-0293`	Criar ou atualizar a configuração de provider	Uma entrada de `schemaBindings` está malformada.
`FLK-0942`	Criar ou atualizar a configuração de provider	Uma entrada de `schemaBindings` nomeia um documento que não existe no seu tenant.
`FLK-0943`	Criar ou atualizar a configuração de provider	Uma entrada de `schemaBindings` restringe a uma operação que o documento não declara.
`FLK-0949`	Tempo de execução	Nem `config.base_url` nem uma entrada `servers` utilizável resolvem uma URL base. O node falha sem chamar o serviço.
`FLK-0950`	Tempo de execução	A operação vinculada não está no documento, ou um parâmetro `path` não encontrou valor. O node falha sem chamar o serviço.
`FLK-0945`	Excluir o documento	Uma configuração de provider ativa o vincula.
`FLK-0936`	Excluir o documento	Um workflow ativo o referencia a partir de um trigger de webhook.
`FLK-0803`	Subir uma versão de especificação	Aquele par de serviço e versão já está publicado. As versões são imutáveis.
`FLK-0801`	Fixar uma versão de especificação	A requisição não traz o serviço ou a versão.

Veja a Lista de erros do Flowker para todos os códigos.

Próximos passos

Trabalhando com os dados da requisição e da resposta

Mapeie valores para o corpo da requisição da operação e leia a resposta dela de volta.

Configurando um trigger de webhook

Valide um payload de entrada contra uma operação do mesmo documento.

Guia de integração

Defina a autenticação, as retentativas e o circuit breaker que cada configuração de provider compartilha.

API de schemas OpenAPI

Explore os endpoints do registro de schemas.

Visão geral

Guias

Console

Operações

Conectando a sua própria API

Antes de começar

Passo 1: Suba o documento OpenAPI

Por qual chave um documento armazenado é identificado

Passo 2: Veja as operações que você pode chamar

Passo 3: Aponte uma configuração de provider para o documento

Para onde vai a credencial

Onde as listas de hosts permitidos são definidas

Vincule o documento

Passo 4: Enderece uma operação a partir de um node de workflow

Como a requisição é montada

Passo 5: Execute e confirme que funcionou

Publicando uma nova versão do seu documento

Versões de especificação dos serviços do catálogo

Removendo um documento

O que pode dar errado

Próximos passos

Trabalhando com os dados da requisição e da resposta

Configurando um trigger de webhook

Guia de integração

API de schemas OpenAPI

​Antes de começar

​Passo 1: Suba o documento OpenAPI

​Por qual chave um documento armazenado é identificado

​Passo 2: Veja as operações que você pode chamar

​Passo 3: Aponte uma configuração de provider para o documento

​Para onde vai a credencial

​Onde as listas de hosts permitidos são definidas

​Vincule o documento

​Passo 4: Enderece uma operação a partir de um node de workflow

​Como a requisição é montada

​Passo 5: Execute e confirme que funcionou

​Publicando uma nova versão do seu documento

​Versões de especificação dos serviços do catálogo

​Removendo um documento

​O que pode dar errado

​Próximos passos

Trabalhando com os dados da requisição e da resposta

Configurando um trigger de webhook

Guia de integração

API de schemas OpenAPI

Antes de começar

Passo 1: Suba o documento OpenAPI

Por qual chave um documento armazenado é identificado

Passo 2: Veja as operações que você pode chamar

Passo 3: Aponte uma configuração de provider para o documento

Para onde vai a credencial

Onde as listas de hosts permitidos são definidas

Vincule o documento

Passo 4: Enderece uma operação a partir de um node de workflow

Como a requisição é montada

Passo 5: Execute e confirme que funcionou

Publicando uma nova versão do seu documento

Versões de especificação dos serviços do catálogo

Removendo um documento

O que pode dar errado

Próximos passos