API de conexões privadas

Use estas rotas para consultar os recursos visíveis de uma organização, criar e remover conexões privadas entre aplicações, Jobs agendados, bancos de dados e Valkey, e salvar a posição dos cartões do mapa. O layout é independente e não altera conexões, permissões nem configurações dos recursos.

Autenticação e autorização

Estas rotas exigem uma sessão de usuário válida. Chaves de API não são aceitas e retornam 401. Selecione a organização ativa: o valor do cabeçalho x-organization-id deve corresponder ao ID da organização na rota.

Authorization: Bearer <user-token>
x-organization-id: <organization-id>
Content-Type: application/json

Para consultar o mapa, o usuário precisa poder ver os recursos da organização. Para criar ou remover uma conexão, são necessárias duas permissões:

O proprietário da organização tem todas as permissões. As respostas descrevem apenas recursos que o usuário pode consultar e não incluem credenciais nem detalhes de implementação.

URL base e rotas

https://api.zenifra.com/v1

Consultar o mapa

GET /v1/organizations/:id/connections

A resposta usa o envelope { "data": ... } e contém nodes (recursos visíveis) e connections (conexões entre recursos). Origens podem ser aplicações HTTP e Jobs agendados; destinos podem ser aplicações HTTP, PostgreSQL, MariaDB, ClickHouse e Valkey. Bancos de dados e Valkey nunca são origem, e Jobs nunca são destino.

{
  "data": {
    "nodes": [
      {
        "id": "<application-id>",
        "name": "Checkout API",
        "kind": "application",
        "status": "<resource-status>",
        "eligible": true,
        "sourceEligible": true,
        "targetEligible": true,
        "internalHostname": "checkout-api.6a11bedda78ad3108eb20e2c.zenifra.local"
      },
      {
        "id": "<another-application-id>",
        "name": "Orders worker",
        "kind": "application",
        "status": "<resource-status>",
        "eligible": true,
        "sourceEligible": true,
        "targetEligible": true
      },
      {
        "id": "<database-id>",
        "name": "Orders PostgreSQL database",
        "kind": "database",
        "status": "<resource-status>",
        "eligible": true,
        "sourceEligible": false,
        "targetEligible": true,
        "internalHostname": "orders-db.6a11bedda78ad3108eb20e2c.zenifra.local",
        "internalPort": 5432,
        "internalReadHostname": "ro.orders-db.6a11bedda78ad3108eb20e2c.zenifra.local"
      },
      {
        "id": "<job-id>",
        "name": "Nightly report",
        "kind": "job",
        "status": "<resource-status>",
        "eligible": true,
        "sourceEligible": true,
        "targetEligible": false
      }
    ],
    "connections": [
      {
        "id": "<connection-id>",
        "sourceId": "<another-application-id>",
        "targetId": "<application-id>",
        "status": "active"
      }
    ]
  }
}

Recursos (nodes)

Conexões (connections)

Uma conexão failed indica que a última operação não foi concluída. Repita a mesma chamada (PUT se failedAction é connect, DELETE se é disconnect) para tentar de novo.

Criar uma conexão

PUT /v1/organizations/:id/connections/:sourceId/:targetId

A requisição não tem corpo. A conexão vale somente de sourceId para targetId; para permitir o sentido oposto, crie outra conexão. A origem chama uma aplicação de destino em http://<projeto>.<id-da-organização>.zenifra.local, em HTTP na porta padrão; essa chamada trafega só dentro da rede privada da organização, e o tráfego público continua em HTTPS. Para um banco de dados ou Valkey, a origem conecta no mesmo endereço, na porta de internalPort, com TLS sem verificação de nome (por exemplo, sslmode=require; o nome do parâmetro varia por cliente); as credenciais continuam as mesmas do banco. O endereço usa o identificador da organização (24 caracteres hexadecimais) para ser único e não muda se o projeto ou a organização forem renomeados.

A resposta contém { "status": "success", "data": <conexão> }, com a conexão no mesmo formato de um item de connections.

{
  "status": "success",
  "data": {
    "id": "<connection-id>",
    "sourceId": "<another-application-id>",
    "targetId": "<application-id>",
    "status": "active"
  }
}

Uma aplicação de origem pode ser reiniciada para aplicar a mudança, e o endereço fica disponível em todas as instâncias dela depois que o reinício terminar. Um Job agendado não reinicia: a mudança vale para as próximas execuções.

Remover uma conexão

DELETE /v1/organizations/:id/connections/:sourceId/:targetId

Responde 204 e é idempotente: remover uma conexão que não existe também retorna 204. Novas conexões do par são bloqueadas na hora. Conexões já abertas não são interrompidas pelo desligamento em si, mas podem ser encerradas se uma aplicação de origem for reiniciada para aplicar a mudança.

Erros

Em 409 por operação em andamento ou destino ainda não pronto, aguarde e repita a chamada. Mensagens de erro são sanitizadas e não expõem detalhes de implementação.

Consultar e salvar o layout

GET /v1/organizations/:id/connection-layout

O layout é individual por usuário e organização e tem o formato abaixo:

{
  "data": {
    "positions": [
      { "projectId": "<resource-id>", "x": 160, "y": 80 },
      { "projectId": "<another-resource-id>", "x": 520, "y": 80 }
    ]
  }
}

Salve posições com PUT /v1/organizations/:id/connection-layout, enviando { "positions": [...] }. Cada item contém projectId, x e y. A lista pode ter até 5.000 posições; as coordenadas devem ser números finitos entre -100000 e 100000, e cada ID precisa pertencer a um recurso que o usuário pode consultar naquela organização.

Mover um cartão altera somente esse layout. Essa operação não cria nem remove conexões.

Próximos passos

• Leia o guia de conexões privadas.
• Consulte a visão geral da API.
• Revise as regras de acesso a organizações.