Tu primera query

Si no has usado GraphQL antes, esta es la versión corta: describes la forma de la respuesta que quieres, y esa es la forma que recibes.

Pide un versículo

GraphQL

query {
  verse(translation: "spa-rv1909", book: "JHN", chapter: 3, verse: 16) {
    bookName
    chapter
    verse
    text
  }
}

cURL

curl https://bibleql.org/graphql \
  -H "Authorization: Bearer $BIBLEQL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"query { verse(translation: \"spa-rv1909\", book: \"JHN\", chapter: 3, verse: 16) { bookName chapter verse text } }"}'

Ruby

require "bibleql"

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

verse = client.verse("JHN", 3, 16, translation: "spa-rv1909")

puts "#{verse.book_name} #{verse.chapter}:#{verse.verse}"
puts verse.text

Node.js

import { BibleQLClient } from "bibleql-js";

const client = new BibleQLClient({
  apiKey: process.env.BIBLEQL_API_KEY!,
  apiUrl: "https://bibleql.org/graphql",
});

const verse = await client.verse("JHN", 3, 16, {
  translation: "spa-rv1909",
});

console.log(`${verse.bookName} ${verse.chapter}:${verse.verse}`, verse.text);

Response

{
  "data": {
    "verse": {
      "bookName": "Juan",
      "chapter": 3,
      "verse": 16,
      "text": "Porque de tal manera amó Dios al mundo, que ha dado á su Hijo unigénito, para que todo aquel que en él cree, no se pierda, mas tenga vida eterna."
    }
  }
}

Fíjate en book: "JHN". El id canónico de tres letras funciona en todas las traducciones. Un nombre localizado como "Juan" también funciona, siempre que corresponda a la traducción que estás consultando.

Pide más campos

Añadir campos es libre: nada llega si no lo pides, y nada se oculta si lo pides. Agregar bookId a la query anterior lo devuelve junto al resto; quitar text evita que se envíe el texto del versículo.

Esa es la diferencia práctica principal con una API REST: el tamaño de la respuesta lo decides tú, no el servidor.

Pide un capítulo completo

GraphQL

query {
  chapter(translation: "spa-rv1909", book: "JHN", chapter: 3) {
    verse
    text
  }
}

cURL

curl https://bibleql.org/graphql \
  -H "Authorization: Bearer $BIBLEQL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"query { chapter(translation: \"spa-rv1909\", book: \"JHN\", chapter: 3) { verse text } }"}'

Ruby

require "bibleql"

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

verses = client.chapter("JHN", 3, translation: "spa-rv1909")

verses.each { |v| puts "#{v.verse}. #{v.text}" }

Node.js

import { BibleQLClient } from "bibleql-js";

const client = new BibleQLClient({
  apiKey: process.env.BIBLEQL_API_KEY!,
  apiUrl: "https://bibleql.org/graphql",
});

const verses = await client.chapter("JHN", 3, {
  translation: "spa-rv1909",
});

verses.forEach((v) => console.log(`${v.verse}. ${v.text}`));

Response

{
  "data": {
    "chapter": [
      {
        "verse": 1,
        "text": "Y HABÍA un hombre de los Fariseos que se llamaba Nicodemo, príncipe de los Judíos."
      },
      {
        "verse": 2,
        "text": "Este vino á Jesús de noche, y díjole: Rabbí, sabemos que has venido de Dios por maestro; porque nadie puede hacer estas señales que tú haces, si no fuere Dios con él."
      },
      {
        "verse": 3,
        "text": "Respondió Jesús, y díjole: De cierto, de cierto te digo, que el que no naciere otra vez, no puede ver el reino de Dios."
      },
      // ... 33 more
    ]
  }
}

chapter devuelve una lista de versículos. Todos los campos de lista del esquema se comportan igual: seleccionas los campos que quieres de cada elemento.

Anida a través de relaciones

Los tipos se conectan entre sí, así que una petición puede recorrer varios niveles:

query {
  translation(identifier: "spa-rv1909") {
    name
    books {
      bookId
      name
      chapterCount
    }
  }
}

Eso devuelve la traducción y todos sus libros con su número de capítulos, en una sola ida y vuelta.

El anidamiento tiene límites

Las queries están limitadas a profundidad 15 y complejidad 300. Una query muy anidada — por ejemplo todos los capítulos y todos los versículos de todos los libros — será rechazada en lugar de servirse lentamente. Usa bibleIndex para la estructura y luego pide el texto que realmente necesites.

Usa variables en lugar de interpolar cadenas

Cuando una query vive en el código de una aplicación, pasa los valores como variables en vez de construir el documento concatenando cadenas:

query GetPassage($translation: String!, $reference: String!) {
  passage(translation: $translation, reference: $reference) {
    reference
    text
  }
}

{
  "translation": "spa-rv1909",
  "reference": "Juan 3:16"
}

Envíalas en la clave variables, junto a query, en el cuerpo del POST. Así el documento queda estático y cacheable, y evitas errores de comillas.

Nombra tus operaciones

query GetPassage(...) es una operación con nombre. Los nombres no cuestan nada y hacen que los logs del servidor y las herramientas de cliente sean mucho más legibles. Una query { ... } anónima está bien para explorar.

Siguiente

• Referencias bíblicas — todo lo que acepta el argumento reference
• Referencia de la API — el esquema completo
• SDKs — evita GraphQL y llama métodos