Guia de Uso da API

Introdução

Este guia descreve como aplicar filtros às consultas na API, permitindo que você recupere dados baseados em critérios específicos. A API oferece suporte para filtros em campos diretos e em campos relacionados, utilizando operadores específicos.

Estrutura dos Filtros

Os filtros são aplicados a endpoints que retornam coleções de itens, permitindo que você selecione itens com base em condições definidas.

{
  "filters": [
      {
          "name": "field_name",
          "op": "operation",
          "val": "value"
      }
  ]
}

• name: O nome do campo que você deseja filtrar.
• op: A operação que será realizada no campo (ex.: eq para igual, lt para menor que, etc.).
• val: O valor contra o qual o campo será comparado.

Exemplo de Filtro

Para buscar todos os itens onde age é maior que 30:

{
  "filters": [
      {
          "name": "age",
          "op": "gt",
          "val": 30
      }
  ]
}

Operações Suportadas

A API suporta as seguintes operações:

• eq: Igual a (=).
• ne: Diferente de (!=).
• lt: Menor que (<).
• le: Menor ou igual a (<=).
• gt: Maior que (>).
• ge: Maior ou igual a (>=).
• like: Similar ao operador SQL LIKE (uso de curingas % e _).
• in: Verifica se o valor está dentro de uma lista.

Exemplo de Filtro com Operações Compostas

Para buscar itens onde age é maior que 30 e name começa com "John":

{
  "filters": [
      {
          "name": "age",
          "op": "gt",
          "val": 30
      },
      {
          "name": "name",
          "op": "like",
          "val": "John%"
      }
  ]
}

Filtros em Campos Relacionados

A API permite que você aplique filtros em campos relacionados, utilizando os operadores any e has.

Operador any

O operador any é usado para filtrar resultados com base em relações one-to-many ou many-to-many, retornando registros que tenham pelo menos um item relacionado que satisfaça o filtro especificado.

Exemplo 1: Filtrando com any em uma Relação one-to-many

Para buscar todos os itens onde a relação posts_relation possui pelo menos um item com mais de 100 likes:

{
  "filters": [
      {
          "name": "posts_relation",
          "op": "any",
          "val": {
              "name": "likes",
              "op": "gt",
              "val": 100
          }
      }
  ]
}

Operador has

O operador has é utilizado para filtrar objetos baseados em uma relação one-to-one ou many-to-one, onde o objeto relacionado deve satisfazer os critérios do filtro.

Exemplo 2: Filtrando com has em uma Relação many-to-one

Para buscar todos os itens onde a relação post_relation está associada a um item publicado em 2023:

{
  "filters": [
      {
          "name": "post_relation",
          "op": "has",
          "val": {
              "name": "publication_year",
              "op": "eq",
              "val": 2023
          }
      }
  ]
}

Exemplo 3: Filtrando com any em Relações many-to-many

Para buscar todos os itens onde a relação books_relation possui pelo menos um item categorizado como "Ficção":

{
  "filters": [
      {
          "name": "books_relation",
          "op": "any",
          "val": {
              "name": "genre",
              "op": "eq",
              "val": "Fiction"
          }
      }
  ]
}

Considerações Finais

A aplicação de filtros na API é uma maneira eficaz de personalizar consultas, permitindo a recuperação de dados que atendam exatamente às necessidades do usuário. O uso de any e has possibilita a construção de consultas que atravessam as relações entre diferentes entidades, proporcionando flexibilidade e poder na consulta de dados.