JSONPath em APIs: Um Guia Simples

Você já se viu vasculhando uma enorme resposta JSON, tentando encontrar aquele único dado de que precisa? Se sim, então sabe que pode ser um pouco como procurar uma agulha em um palheiro. Apresentamos o JSONPath - uma ferramenta prática que pode tornar sua vida muito mais fácil ao lidar com dados JSON em APIs.

O que é JSONPath?

JSONPath é uma linguagem de consulta para JSON, semelhante ao XPath para XML. Ela permite que você navegue e extraia partes específicas dos seus dados JSON usando uma sintaxe simples e intuitiva. Pense nisso como uma maneira de executar consultas nos seus dados JSON e obter exatamente o que você precisa, sem precisar mergulhar na resposta inteira.

Por que usar JSONPath?

Imagine que você tem uma enorme resposta JSON de uma API; tudo o que você precisa é o valor de um campo específico aninhado bem no fundo. Sem o JSONPath, você normalmente teria que escrever um monte de código para analisar o JSON, o que pode ser tedioso e propenso a erros. O JSONPath simplifica isso, permitindo que você especifique exatamente o que deseja extrair, tornando seu código mais limpo e fácil de manter.

Como o JSONPath funciona?

O JSONPath usa uma sintaxe semelhante à notação de objetos do JavaScript, com alguns recursos adicionais para consultas mais complexas. Aqui está um resumo rápido da sintaxe básica:

• $: Representa o objeto ou array raiz.
• . ou []: Operador filho; usado para acessar uma propriedade do objeto ou um elemento do array.
• *: Curinga; combina todos os elementos ou campos.
• ..: Descida recursiva; busca nós correspondentes em qualquer nível.
• ?(): Aplica um filtro (a expressão deve avaliar como verdadeira).
• (): Expressão de script, usando o mecanismo de script subjacente.

Vamos nos aprofundar em alguns exemplos para ver o JSONPath em ação.

Exemplos Básicos de JSONPath

Considere os seguintes dados JSON de uma API de banco de dados de filmes:

{
  "movies": {
    "action": [
      { "title": "Mad Max: Estrada da Fúria", "director": "George Miller", "year":                  2015, "rating": 8.1 },
      { "title": "John Wick", "director": "Chad Stahelski", "year": 2014,                     "rating": 7.4 }
    ],
    "drama": [
      { "title": "Os Intocáveis", "director": "Frank Darabont",                   "year": 1994, "rating": 9.3 },
      { "title": "Forrest Gump", "director": "Robert Zemeckis", "year":                       1994, "rating": 8.8 }
    ],
    "comedy": [
      { "title": "O Grande Hotel Budapeste", "director": "Wes Anderson",                     "year": 2014, "rating": 8.1 }
    ]
  }
}

Extraindo todos os filmes de ação:

$.movies.action[*]

Isso lhe dará um array com todos os objetos de filmes de ação.

Extraindo os títulos de todos os filmes de drama:

$.movies.drama[*].title

Isso retornará um array com os títulos de todos os filmes de drama: ["Os Intocáveis", "Forrest Gump"].

Extraindo a avaliação de "Mad Max: Estrada da Fúria":

$.movies.action[?(@.title == "Mad Max: Estrada da Fúria")].rating

Isso retornará a avaliação de "Mad Max: Estrada da Fúria": 8.1.

Encontrando todos os filmes lançados em 2014:

$.movies..[?(@.year == 2014)]

Isso retornará todos os filmes lançados em 2014, que neste caso são: ["John Wick", "O Grande Hotel Budapeste"].

JSONPath em APIs

Usar JSONPath em APIs é incrivelmente útil quando você deseja extrair informações específicas de uma resposta JSON. Muitas linguagens de programação e ferramentas possuem bibliotecas que suportam JSONPath, facilitando sua integração em seus projetos.

Por exemplo, em Javascript, você pode usar a biblioteca jsonpath:

const jsonpath = require('jsonpath');

// Dados JSON de exemplo
const data = {
  movies: {
    action: [
      { title: "Mad Max: Estrada da Fúria", director: "George Miller", year: 2015, rating: 8.1 },
      { title: "John Wick", director: "Chad Stahelski", year: 2014, rating: 7.4 }
    ],
    drama: [
      { title: "Os Intocáveis", director: "Frank Darabont", year: 1994, rating: 9.3 },
      { title: "Forrest Gump", director: "Robert Zemeckis", year: 1994, rating: 8.8 }
    ],
    comedy: [
      { title: "O Grande Hotel Budapeste", director: "Wes Anderson", year: 2014, rating: 8.1 }
    ]
  }
};

// Extraindo títulos de todos os filmes de drama
const titles = jsonpath.query(data, '$.movies.drama[*].title');
console.log(titles); // Saída: ["Os Intocáveis", "Forrest Gump"]

Da mesma forma, em Python, você pode usar a biblioteca jsonpath-ng:

from jsonpath_ng import jsonpath, parse

# Dados JSON de exemplo
data = {
    "movies": {
        "action": [
            {"title": "Mad Max: Estrada da Fúria", "director": "George Miller", "year": 2015, "rating": 8.1},
            {"title": "John Wick", "director": "Chad Stahelski", "year": 2014, "rating": 7.4}
        ],
        "drama": [
            {"title": "Os Intocáveis", "director": "Frank Darabont", "year": 1994, "rating": 9.3},
            {"title": "Forrest Gump", "director": "Robert Zemeckis", "year": 1994, "rating": 8.8}
        ],
        "comedy": [
            {"title": "O Grande Hotel Budapeste", "director": "Wes Anderson", "year": 2014, "rating": 8.1}
        ]
    }
}

# Extraindo títulos de todos os filmes de drama
jsonpath_expr = parse('$.movies.drama[*].title')
titles = [match.value for match in jsonpath_expr.find(data)]
print(titles)  # Saída: ["Os Intocáveis", "Forrest Gump"]

Usando JSONPath no Apidog

Apidog é uma ferramenta versátil projetada para simplificar o processo de trabalho com APIs, e ela suporta JSONPath nativamente.

Aqui está como o Apidog pode ajudá-lo a aproveitar o poder do JSONPath de forma eficaz:

Primeiro, você precisará enviar solicitações para suas APIs e visualizar as respostas diretamente com o Apidog. Depois, você pode usar a interface fornecida para aplicar uma consulta JSONPath para extrair os títulos de todos os filmes de ação da resposta.

No screenshot acima, você verá que (1) enviamos uma solicitação GET para nosso servidor - eu criei um servidor express simples usando os dados JSON que obtivemos acima como resposta. Em seguida, mudei para a aba de Processadores Pós (2) e adicionei um novo processo - Extrair Variável (3).

Ao clicar em Extrair Variável, você verá a página abaixo;

Você pode definir um nome de variável (1) se desejar. As variáveis são úteis se você quiser monitorar ou construir diferentes APIs e precisa de um único lugar para gerenciar a configuração geral. As variáveis aqui são como arquivos .env.

A outra etapa é digitar o JSONPath que você deseja filtrar (2). No nosso caso aqui, queremos obter os títulos dos filmes no array de ação do nosso JSON. Assim que você digitar o caminho atualmente, clique no botão de seta (3) para abrir a página de resposta da consulta, como mostrado abaixo.

Como você pode ver na resposta acima, o Apidog filtrou os títulos dos filmes no array de ação e os exibiu para nós.

Se você quiser experimentar, então não se esqueça de baixar e instalar o Apidog e enviar sua primeira solicitação com ele.

Conclusão

JSONPath é uma ferramenta inestimável para navegar e extrair dados de respostas JSON em APIs. Ela simplifica o processo de trabalhar com estruturas JSON complexas, tornando seu fluxo de desenvolvimento mais eficiente. Ao integrar o JSONPath com ferramentas como o Apidog, você pode facilmente filtrar e recuperar os dados exatos de que precisa, aprimorando seus processos de teste e depuração de APIs. Se você está extraindo títulos de filmes, filtrando registros específicos ou validando respostas, o JSONPath oferece uma maneira clara e concisa de lidar com dados JSON. Experimente em seu próximo projeto e experimente a simplicidade simplificada que ele traz.