O Mastodon tem uma API rica e fácil de operar, e desenvolver clientes ou robôs para interagir com ela está ao seu alcance em várias linguagens.

Desenvolver interfaces ou clientes para o Mastodon tem uma escala de complexidade a ser vencida, como em tudo na vida, mas não há razão para começar já tentando operações difíceis, autenticadas e envolvendo múltiplas instâncias: o ideal é começar com operações simples, envolvendo apenas um endpoint de API por vez, e com acesso a dados públicos, até pegar o jeito e alçar voos mais altos.

O artigo de hoje é introdutório a esse tipo de aplicação para quem já programa e está familiarizado com APIs web. Usaremos um script shell para listar as hashtags em destaque na lista de Trending de uma instância, como as deste exemplo - mas obtendo-as via endpoint da API, e não via scraping da interface web do Mastodon.

A API do Mastodon é bem documentada, e desde já recomendo os capítulos "Getting Started with the API", "Playing with public data" e "trends API methods" para entendimento aprofundado do que apresentarei com bem menos detalhes a seguir.

Para rodar os exemplos abaixo, você precisa ter uma shell Bash ou compatível, com o curl e o gron (para facilitar o consumo das respostas em formato JSON) instalados em um sistema compatível com o Posix (como a maior parte das distribuições Linux, o Mac e Unix em geral).

API do Mastodon: consultando e recebendo a resposta

Em primeiro lugar, perceba que a API do Mastodon é acessada pela web, enviando consultas ou comandos (eventualmente com detalhamento – por exemplo, via campos de formulário ou parâmetros da URL de acesso), e recebendo respostas em formato JSON.

Para o nosso exemplo de hoje, usaremos o endpoint "View trending tags" da API do Mastodon, que pode ser acessado – em instâncias abertas – por meio de uma URL como esta: https://social.br-linux.org/api/v1/trends/tags

Acesse a URL acima em um navegador, e você terá como resposta uma longa linha de texto, em formato JSON, listando as hashtags que aquela instância visualiza como estando em destaque naquele momento, e para cada uma delas expondo alguns atributos, como o número de contas que a mencionou, e quantas vezes ela foi mencionada, entre outros.

Trabalhando com a resposta da API

Ao fazer o acesso acima no navegador, você já usou a API da mesma forma que outros recursos mais avançados fariam, porém recebeu a resposta em um formato inconveniente para operar - ao contrário do que aconteceria quando acessamos por meio de bibliotecas mais avançadas, como a Mastodon.py e várias outras bibliotecas Mastodon para várias linguagens.

Vamos conhecer e destrinchar a resposta da API de trending tags, item por item.

Hoje não veremos o uso dessas bibliotecas, mas sim destrincharemos a resposta da API nesse endpoint - escolhido como exemplo por ser simples – para fixar melhor o funcionamento.

Em primeiro lugar, acesse o endpoint a partir da shell, usando os já mencionados curl e gron, para ver uma versão formatada da resposta da API. Para isso, digite:

curl -s "https://social.br-linux.org/api/v1/trends/tags" | gron

Observe que a resposta traz uma série de tags, e para cada uma delas são apresentadas as estatísticas diárias, como no trecho do exemplo:

(...)
json[7].history[0] = {};
json[7].history[0].accounts = "22";
json[7].history[0].day = "1720483200";
json[7].history[0].uses = "29";
(...)
json[7].name = "introductions";
json[7].url = "https://social.br-linux.org/tags/introductions";
(...)

Veja que destaquei duas linhas, por serem justamente as que nos interessam para esse exemplo: a visão da instância sobre o número de contas diferentes que usaram a tag hoje (history[0].accounts) e o nome da tag (name).

A partir dessa percepção, e com uso de expressões regulares para selecionar linhas como as duas destacadas acima, chegamos ao script a seguir:

#!/usr/bin/env bash
#
# bot_exemplo.sh - exibe as hashtags em destaque em uma instância do Mastodon
#
# Copyright (c) 2024,  Augusto Campos (http://augustocampos.net/).
# Licensed under the Apache License, Version 2.0.
#

instancia="https://social.br-linux.org"

curl -s "$instancia/api/v1/trends/tags" | gron | awk '

/0].accounts/ { gsub(/(.* = |[";])/,""); contas=$0 }
/\.name/      { gsub(/.* = |[";]/,""); print contas, $0 }

' | sort -nr 

Ele faz a consulta à API (curl e gron), filtra com o awk as linhas como as destacadas acima, extraindo delas só os valores (removendo as aspas, os ponto-e-vírgulas e tudo o que vem antes do sinal de igual), e ao final classifica (sort) as tags em ordem das que foram mencionadas por mais contas.

Executá-lo hoje gerou a saída a seguir:

Note que no formato atual, esse script seria mais adequadamente descrito como um cliente do que como um bot. Mesmo assim, a funcionalidade dele é parte integrante do bot que gera os dados para a curadoria do perfil @TrendsBR, e possivelmente outras peças desse mesmo bot (ou de outros que mantenho) voltarão a ilustrar artigos futuros aprofundando os conceitos que hoje começamos a ver.