API de conexões entre aplicações

Use estas rotas para consultar os recursos visíveis de uma organização, criar e remover conexões privadas entre aplicações 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 aplicações).

{
  "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": false,
        "sourceEligible": false,
        "targetEligible": false,
        "reason": "<reason>"
      }
    ],
    "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 o 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. 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"
  }
}

A aplicação de origem pode ser reiniciada para aplicar a mudança. O endereço fica disponível em todas as instâncias dela depois que o reinício terminar.

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 a 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 internas entre aplicações.
• Consulte a visão geral da API.
• Revise as regras de acesso a organizações.