Configurar los SDKs

Los clientes de Ruby y Node se pueden configurar una vez de forma global, o por instancia; el de Python siempre es por instancia. Esta página explica dónde va esa inicialización y qué opciones deberías fijar en lugar de heredar.

Opciones

Los tres SDKs aceptan las mismas cuatro cosas, con nombres propios de cada lenguaje.

Opción	Ruby	Node.js	Python	Por defecto
API key	api_key	apiKey	api_key	ninguna — obligatoria (Python recurre a BIBLEQL_API_KEY)
Endpoint	api_url	apiUrl	api_url	Ruby/Node: una URL alojada en Render, no bibleql.org. Python: https://bibleql.org/graphql
Traducción de respaldo	default_translation	defaultTranslation	default_translation	eng-web
Tiempo de espera	timeout (segundos)	timeout (milisegundos)	timeout (segundos)	30s / 30000ms / 30s

Fíjate en que el tiempo de espera va en milisegundos en Node y en segundos en los otros dos.

Fija siempre el endpoint explícitamente en Ruby y Node

Esos SDKs apuntan hoy por defecto a un host alojado en Render en lugar de a https://bibleql.org/graphql. Si lo dejas sin configurar, tu tráfico va a otro sitio que no es el endpoint canónico. Fíjalo en tu inicializador. El cliente de Python ya usa el endpoint canónico por defecto.

Dónde inicializar

Ruby

En una aplicación Rails, configúralo una sola vez en un inicializador:

config/initializers/bibleql.rb

require "bibleql"

BibleQL.configure do |config|
  config.api_key = ENV.fetch("BIBLEQL_API_KEY")
  config.api_url = "https://bibleql.org/graphql"
  config.default_translation = "spa-rv1909"
  config.timeout = 30
end

Y después, en cualquier parte de la aplicación:

BibleQL.client.passage("Juan 3:16")

Usar ENV.fetch sin valor por defecto es intencional: falla de forma ruidosa al arrancar si falta la key, en lugar de fallar en la primera petición en producción.

Usar las credenciales de Rails

Si guardas los secretos en config/credentials.yml.enc en lugar de en el entorno:

config/initializers/bibleql.rb

BibleQL.configure do |config|
  config.api_key = Rails.application.credentials.bibleql!(:api_key)
  config.api_url = "https://bibleql.org/graphql"
end

Edítalas con bin/rails credentials:edit:

bibleql:
  api_key: bql_live_...

Clientes por instancia

La configuración global es cómoda pero compartida. Para una traducción distinta, otro tiempo de espera o un cliente aislado en los tests, créalo directamente:

client = BibleQL::Client.new(
  api_key: ENV.fetch("BIBLEQL_API_KEY"),
  api_url: "https://bibleql.org/graphql",
  default_translation: "spa-rv1909"
)

Un cliente por instancia ignora la configuración global, lo que lo convierte en la mejor opción para los tests: no hay estado global que reiniciar entre ejemplos.

Ruby sin Rails

No hay directorio de inicializadores, así que configúralo una vez al cargar, antes del primer uso:

require "bibleql"

BibleQL.configure do |config|
  config.api_key = ENV.fetch("BIBLEQL_API_KEY")
  config.api_url = "https://bibleql.org/graphql"
end

Node.js

Exporta un único cliente configurado desde un módulo e impórtalo donde lo necesites. Crear un cliente por petición funciona, pero es crear objetos sin necesidad.

lib/bibleql.ts

import { BibleQLClient } from "bibleql-js";

const apiKey = process.env.BIBLEQL_API_KEY;

if (!apiKey) {
  // Falla al arrancar, no en la primera petición.
  throw new Error("BIBLEQL_API_KEY no está configurada");
}

export const bibleql = new BibleQLClient({
  apiKey,
  apiUrl: "https://bibleql.org/graphql",
  defaultTranslation: "spa-rv1909",
  timeout: 30_000,
});

import { bibleql } from "./lib/bibleql";

const passage = await bibleql.passage("Juan 3:16");

La comprobación explícita de apiKey además estrecha el tipo de string | undefined a string, y por eso el módulo anterior no necesita el operador de aserción no nula.

Configuración global

El paquete también admite configuración para todo el proceso:

import { configure } from "bibleql-js";

configure({
  apiKey: process.env.BIBLEQL_API_KEY!,
  apiUrl: "https://bibleql.org/graphql",
  defaultTranslation: "spa-rv1909",
});

Para código de aplicación es preferible el enfoque del módulo exportado: mantiene la dependencia explícita y es mucho más fácil de sustituir en los tests. configure() resulta útil en un script o en una REPL.

Next.js y otros frameworks

Importa el cliente solo desde código de servidor: un route handler, un server component, una server action, getServerSideProps. Si un módulo que importa bibleql-js es alcanzable desde un componente de cliente, tu key acaba en el bundle del navegador.

Guarda la key en .env.local como BIBLEQL_API_KEY, nunca como NEXT_PUBLIC_BIBLEQL_API_KEY: el prefijo NEXT_PUBLIC_ la publica por diseño.

Serverless y edge

Los arranques en frío vuelven a ejecutar la inicialización del módulo, así que un cliente a nivel de módulo se crea una vez por instancia y se reutiliza entre invocaciones en esa instancia, que es lo que quieres. Solo asegúrate de que la key venga del almacén de secretos de la plataforma y no de un archivo empaquetado.

Python

No hay configuración global: crea un bibleql.Client. En un script, úsalo como context manager para que su pool de conexiones HTTP se cierre al terminar:

import bibleql

with bibleql.Client() as client:  # lee BIBLEQL_API_KEY
    print(client.passage("Juan 3:16", translation="spa-rv1909").text)

En una aplicación, crea un único cliente en un módulo e impórtalo donde lo necesites, para que las conexiones se reutilicen entre peticiones:

app/bibleql_client.py

import os

import bibleql

bibleql_client = bibleql.Client(
    api_key=os.environ["BIBLEQL_API_KEY"],
    default_translation="spa-rv1909",
    timeout=30,
)

from app.bibleql_client import bibleql_client

passage = bibleql_client.passage("Juan 3:16")

os.environ["BIBLEQL_API_KEY"] falla de forma ruidosa al importar si falta la key. Si omites api_key, el cliente lee la misma variable y lanza bibleql.ConfigurationError.

Django, Flask, FastAPI

El cliente a nivel de módulo funciona en los tres. Llama a bibleql_client.close() desde el hook de apagado de tu framework —por ejemplo el lifespan de FastAPI— si quieres liberar las conexiones limpiamente.

Archivos .env

La librería nunca lee archivos .env por sí misma. Cárgalos antes de crear el cliente, por ejemplo con python-dotenv:

from dotenv import load_dotenv

load_dotenv()
client = bibleql.Client()

Elegir una traducción por defecto

default_translation / defaultTranslation solo se aplica cuando una llamada omite la traducción. No restringe nada: cualquier llamada puede pasar otra distinta. (La única excepción es semantic_search en Python: ignora el valor por defecto y deja que la API elija una traducción con embeddings.)

Configúrala con la que tu aplicación muestre más a menudo. Si sirves varios idiomas, es preferible pasar translation explícitamente en cada llamada, para que el comportamiento no dependa de una configuración escrita en otro sitio.

Tiempos de espera

Los valores por defecto (30 segundos) son generosos para casi todas las queries. Dos cosas que conviene saber:

• semanticSearch llama a un servicio externo de embeddings y es la query más lenta de la API. Si la usas dentro de una petición de usuario, un tiempo de espera más corto con un plan alternativo es mejor que una página colgada.
• Las páginas grandes de concordance tardan más que buscar un versículo. Reduce first antes de subir el tiempo de espera.

Verificar tu configuración

Una query económica que no toca texto bíblico:

Ruby

translations = BibleQL.client.translations
puts "#{translations.size} traducciones disponibles"

Node.js

const translations = await bibleql.translations();
console.log(`${translations.length} traducciones disponibles`);

Python

translations = bibleql_client.translations()
print(f"{len(translations)} traducciones disponibles")

Si la key es incorrecta recibirás un error de autenticación de inmediato — consulta Errores para ver cómo se ve cada fallo, y SDKs para la clase de excepción a la que corresponde cada uno.

Usa una key de pruebas en local

Apunta el entorno de desarrollo a una key bql_test_. Producción rechaza las keys de entorno de pruebas, así que una key filtrada desde un portátil o desde los logs de CI no puede gastar tu cuota real. Consulta API Keys.