API

1. Geral

No Mitra, é possível integrar seus dados com qualquer outro sistema via API. Esta API permite que você consulte, insira, atualize e remova dados de tabelas através de chamadas REST. A autenticação é feita por meio de um token Bearer, e a interação com os dados é facilitada pelo uso de filtros e operadores no query parameter allParams.

2. Como criar e gerenciar chaves de API no Mitra:

• Navegue até a tela de “Configurações Gerais” do seu projeto.

• Encontre a seção “API” e crie uma nova chave.

• A URL e a chave privada serão geradas automaticamente, e são utilizadas na integração de seus dados com outros sistemas. 

• Nas configurações da API, você poderá definir quais tabelas do seu database deseja compartilhar.

• Use essa chave privada em suas chamadas API, conforme as instruções de autenticação.

2.1. Base URL

2.2. Autenticação

Para realizar chamadas à API, é necessário incluir o header de autorização:

Authorization: Bearer {chave_privada}

• Exemplo:

--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJUYXNrcyIsIlgtVGVuYW50SUQiOiJ0ZW5hbnRfNzc2NSJ9.RxBv3P1Rz6B1AQTopqANqytgPhbInJKIHVUWWGlOcV3xv6L6QTajIoF_dBWXdRNspNGKjWGJ4F2PB7YB7_VV8g'

3. Endpoints

Um endpoint é como uma "porta" da API que permite acessar ou modificar dados. Cada endpoint tem um endereço (URL) e está ligado a uma ação específica, como buscar, enviar, atualizar ou apagar dados.

Exemplos de ações que podem ser feitas com endpoints:

• GET: Buscar dados (exemplo: pegar informações de tarefas).

• POST: Enviar dados (exemplo: adicionar uma nova tarefa).

• PUT: Atualizar dados (exemplo: editar informações de uma tarefa existente).

• DELETE: Remover dados (exemplo: excluir uma tarefa).

3.1. Consultar Dados (GET)

Busca dados da tabela especificada, permitindo filtros dinâmicos via query parameters.

Endpoint:

GET /{tableName}

Exemplo:

curl --location 'https://api0.mitraecp.com:2409/rest/v0/Task?status=Ativo&horas_gt=4' \
--header 'Authorization: Bearer your_token_here'

3.1.1. Query Parameters

• allParams: Parâmetros dinâmicos usados como filtros (exemplo: status, horas_gt, etc.).

• page: Página de resultados (default: 0).

• size: Quantidade de resultados por página (default: 10).

• sort: Coluna para ordenação.

• order: Ordem da ordenação (ASC/DESC, default: ASC).

Exemplo com Filtros e Paginação:

curl --location 'https://api0.mitraecp.com:2409/rest/v0/Task?status=Ativo&horas_gt=4&page=1&size=20&sort=horas&order=DESC' \
--header 'Authorization: Bearer your_token_here'

3.1.2. Operadores Suportados em allParams

• gt: Maior que (field_gt=value)

• lt: Menor que (field_lt=value)

• gte: Maior ou igual (field_gte=value)

• lte: Menor ou igual (field_lte=value)

• eq: Igual (field=value)

• neq: Diferente (field_neq=value)

• like: Contém (field_like=value)

Exemplo de Filtros:

• status=Ativo: Filtra registros com status = 'Ativo'.

• horas_gt=4: Filtra registros onde horas > 4.

• data_lte=2023-12-31: Filtra registros onde a data seja menor ou igual a 31/12/2023.

3.2. Inserir Dados (POST)

Insere um ou mais registros em uma tabela.

Endpoint:

POST /{tableName}

Exemplo:

curl --location 'https://api0.mitraecp.com:2409/rest/v0/Task' \
--header 'Authorization: Bearer your_token_here' \
--header 'Content-Type: application/json' \
--data-raw '[
  {
    "Descrição": "Desenvolver nova funcionalidade",
    "ID Solicitante": "12345",
    "ID Origem": "54321",
    "Horas": "10",
    "Data de Abertura": "2023-09-01",
    "Observações": "Entrega até o final do mês"
  }
]

Corpo da Requisição: Envie os dados em formato JSON, com cada campo e valor correspondente ao registro a ser inserido.

3.3. Atualizar Dados (PUT)

Atualiza um ou mais registros em uma tabela.

Endpoint:

PUT /{tableName}

Exemplo:

curl --location 'https://api0.mitraecp.com:2409/rest/v0/Task' \
--header 'Authorization: Bearer your_token_here' \
--header 'Content-Type: application/json' \
--data-raw '[
  {
    "Descrição": "Atualizar a funcionalidade existente",
    "ID Solicitante": "12345",
    "ID Origem": "54321",
    "Horas": "12",
    "Data de Abertura": "2023-09-01",
    "Observações": "Entrega antecipada"
  }
]

Corpo da Requisição: O corpo deve ser um JSON com os dados atualizados para os registros na tabela.

3.4. Deletar Dados (DELETE)

Remove um registro de uma tabela com base no dimensionContentId.

Endpoint:

DELETE /{tableName}/{dimensionContentId}

Exemplo:

curl --location --request DELETE 'https://api0.mitraecp.com:2409/rest/v0/Task/12345' \
--header 'Authorization: Bearer your_token_here'

4. Filtros Avançados

Os filtros na API são realizados por meio de query parameters que podem ser incluídos diretamente na URL. Eles suportam uma série de operadores para facilitar as buscas.

Exemplos de Filtros:

• Filtrar por igualdade:

  curl 'https://api0.mitraecp.com:2409/rest/v0/Task?status=Ativo'

  
  

• Filtrar por maior que (gt):

  curl 'https://api0.mitraecp.com:2409/rest/v0/Task?horas_gt=4'

  
  

• Filtrar por menor ou igual (lte):

  curl 'https://api0.mitraecp.com:2409/rest/v0/Task?data_lte=2023-12-31'

  
  

• Combinação de Filtros:

  curl 'https://api0.mitraecp.com:2409/rest/v0/Task?status=Ativo&horas_gt=4'

Os filtros podem ser combinados com outros parâmetros, como paginação (page), tamanho da página (size), ordenação (sort) e direção da ordenação (order).