albanirneves / firebird-api

Uma API Rest NodeJS que recebe um SQL, envia para um banco de dados Firebird e retorna um JSON.

Firebird API

Uma API Rest NodeJS que recebe um SQL, envia para um banco de dados Firebird e retorna um JSON.

Instalação

npm install 

Você também precisa criar as variáveis de ambiente com usuário e senha do seu banco de dados:

FIREBIRDAPI_USER: SYSDBA
FIREBIRDAPI_PASSWORD: masterkey

Você também precisa criar o arquivo src/config.json com a seguinte estrutura:

{
    "connection": {
        "database": "C:/dados/database.fdb",
        "host": "127.0.0.1",
        "port": 3050,
        "pageSize": 4096
    },
    "secret": "minha_chave_secreta",
    "enableBlobSubtypeText": false,
    "cors": {
        "allowServerToServerAccess": false,
        "whitelist": ["meusite.com.br"]
    }
}

• connection.database: O endereço físico do seu banco de dados.
• connection.host: A URL ou IP do servidor onde se encontra seu banco de dados.
• connection.port: A porta do firebird no seu servidor.
• connection.pageSize: Opcional Default 4096. O pageSize ideal de acordo com seu banco e servidor.
• secret: A chave secreta que foi utilizada para gerar o token JWT
• enableBlobSubtypeText: Opcional Default false. Recomendado false Utilizando o padrão recomendado false a API conseguirá ler apenas campos BLOB do tipo binário (BLOB SUB_TYPE 0 Binary). Esta opção é recomendada porque a comunidade node-firebird ainda não conseguiu ler campos BLOB do tipo texto (BLOB SUB_TYPE 1 Text) com segurança. Veja aqui a issue ainda aberta no github sobre este problema, onde propus uma solução temporária de utilizarmos apenas campos BLOB do tipo binário, como essa opção faz por default. Caso você não tenha acesso ou não seja possível alterar o seus campos BLOB para tipo binário, faça testes habilitando essa opção para true, assim a API conseguirá ler automaticamente campos BLOB SUB_TYPE 1 Text. Essa opção não é recomendada pois para isso internamente é usado um fork do pacote node-firebird oficial, chamado node-firebird-dev que consegue contornar alguns problemas e ler esse tipo de blob. Porém esse pacote não recebe frequentes atualizações e pode trazer outros problemas . Habilite essa opção apenas se você tiver certeza do que está fazendo.
• cors.allowServerToServerAccess: Opcional Default false. Se true o cors permite que a API seja acessada diretamente de outros servidores ou de ferramentas REST como Postman, Insomnia, dentre outros.
• cors.whitelist: Uma lista de domínios a partir de onde é permitido acessar a API. Há duasformas possíveis de uso:

1. Recomendado ["meusite.com.br", "meusite2.com.br"] permitirá que sua API seja acessada apenas de dentro de páginas destes domínios.
2. ["*"] permite acesso a partir de qualquer domínio da WEB.

Endpoint

O servidor ficará disponivel na porta indicada na variável de ambiente PORT ou na porta 3000 por padrão.

Acessando o recurso principal:

POST /query
Content-Type: application/json
Authorization: Bearer **seu_token**

{
   "sql": "select * from MY_TABLE"
}

O retorno será um JSON:

[
  {
    "ID": 6,
    "NOME": "José",
    "CIDADE": "São Paulo",
    "ESTADO": "SP"
  },
  {
    "ID": 2,
    "NOME": "Paulo",
    "CIDADE": "Palmas",
    "ESTADO": "TO"
  }
]

A resposta contém um header X-Total-Count com o total de registros retornados.

Problemas com charsets

A conversão dos dados e envio via javascript/firebird às vezes gera problemas relacionados com charset, especialmente se os campos VARCHAR das tabelas estiverem sem Charset ou sem Collate. O retorno é sempre tratado, mas às vezes vocês precisarão realizar alguns workarouds com os sqls.

Por exemplo:

select CODIGO, DATA, OBSERVACOES from CALENDARIO where OBSERVACOES like 'Isenção%'

O sql acima pode não retornar valores devido a acentuação. Veja aqui uma discussão sobre isso Nesse caso sempre é recomendado realizar um cast para varchar(256) character set latin1 no próprio SQL:

select CODIGO, DATA, OBSERVACOES from CALENDARIO where OBSERVACOES like cast('Isenção%' as varchar(256) character set latin1)

Dependências

Esta API utiliza o pacote node-firebird na sua versão mais estável (0.8.9). Atualizações para versões posteriores podem não se comportar corretamente.