API de busca de exercícios: consultas e 6 idiomas

Envie q com uma chave de API. Uma requisição sem q devolve um erro 400. Os resultados vêm no mesmo envelope { data, pagination } da listagem, ordenados por relevância, com empates decididos pelo id. As páginas trazem 50 resultados por padrão e no máximo 100.

curl -H "Authorization: Bearer fed_live_YOUR_KEY" \
  "https://api.fitexercisedb.com/v1/exercises/search?q=squat&pageSize=10&lang=fr"

Cada resultado tem todos os campos descritos na referência dos campos da resposta. Por baixo, é uma consulta de texto completo do PostgreSQL sobre o nome, o músculo alvo e o equipamento; nada mais é indexado.

O índice usa a configuração de texto simple do PostgreSQL, que converte as palavras em minúsculas sem fazer radicalização, e a consulta é montada com plainto_tsquery, que exige cada palavra. Assim, a consulta só encontra palavras inteiras e todas as palavras enviadas precisam estar presentes.

Se precisar de autocompletar, carregue uma vez a taxonomia e os nomes que importam, guarde em cache e filtre localmente; use a busca para a consulta final. Teste consultas no banco de exercícios para ver o conteúdo antes de programar.

Não traduzindo a sua consulta. O texto indexado é o nome, o músculo alvo e o equipamento em inglês; os nomes traduzidos não fazem parte do índice, então uma palavra em francês só encontra algo quando se escreve igual em inglês. O parâmetro lang muda o que volta, não o que é comparado.

O padrão que funciona para uma busca localizada é traduzir você mesmo as palavras do usuário para termos em inglês e depois pedir à API o texto no idioma dele:

// The user types in French. You map it to English terms, then ask for French text back.
const q = toEnglish("développé couché");        // your own mapping: "bench press"
const url = `/v1/exercises/search?q=${encodeURIComponent(q)}&lang=fr`;

Nos casos comuns, dispense o texto livre: ofereça listas de partes do corpo, músculos e equipamentos, mantenha o valor em inglês como chave e mostre um rótulo traduzido.

Três fontes são verificadas em ordem. Vale a primeira suportada, e nada disso é erro:

Os sufixos de região são descartados, então fr-FR e pt-BR viram fr e pt. O cabeçalho é lido na ordem em que está escrito e a primeira etiqueta suportada é usada; os pesos de qualidade não são comparados. Um valor como de não é suportado e devolve inglês silenciosamente. Toda resposta informa qual idioma usou:

Content-Language: fr
Vary: Accept-Language

Como a mesma URL pode devolver textos diferentes conforme o Accept-Language, coloque o idioma na chave de cache ou envie um lang explícito.

Essa última linha é a armadilha. Uma resposta em francês mostra Poitrine para o peito, mas o filtro espera Chest:

# the filter value stays English, the labels come back in French
curl -H "Authorization: Bearer fed_live_YOUR_KEY" \
  "https://api.fitexercisedb.com/v1/exercises?bodyPart=Chest&lang=fr"

Busque as listas de filtros uma vez, sem lang, e guarde esses valores como chaves; as listas exatas estão na documentação.