Guías

API: visión general

Qué publica el sitio como JSON, cómo leerlo, qué se promete que no cambie y cómo llamarlo desde cualquier lenguaje.

La documentación de un plugin no debería copiar lo que es un botón, una tabla o un color: debería apuntar aquí. Todo lo que sabe este sitio se publica como JSON estático, así que cualquier otra documentación, script de build, prueba o editor puede leerlo. Esta página es el mapa; las demás páginas de la guía profundizan en cada parte.

Qué obtienes

Quieres…	Lee	Página de la guía
Saber qué existe y abrir una página en un estado dado	`/api/index.json`	Visión general, Enlaces y estados
Listar cada página y leer su texto	`/api/index.json`, `/api/pages/<id>.json`	Páginas y búsqueda
Copiar el marcado de un componente	`/api/components/<componente>.json`	Componentes y ejemplos
Leer las variables CSS de una versión de Moodle	`/api/tokens/<version>.json`	Tokens y versiones
Dibujar un icono de Moodle con Font Awesome	`/api/icons.json`	Iconos y marca
Usar los colores y el logo de Didactika	`/api/brand.json`	Iconos y marca
Comprobar la forma de cada archivo		Referencia de los archivos

La dirección

GET https://moodle-design.didactika.org/api/index.json

El sitio lo sirve GitHub Pages: no hay clave, ni inicio de sesión, ni límite de uso que gestionar. Cada respuesta es un archivo JSON con Content-Type: application/json y la cabecera Access-Control-Allow-Origin: *, así que también se puede leer desde un navegador en cualquier otro sitio.

El punto de entrada

/api/index.json guarda, en un archivo:

Campo	Qué es
`schema`	La versión de la forma del JSON (mira más abajo)
`name`, `site`, `repository`, `licence`	Qué es esto y dónde vive
`languages`	`["en", "es"]`
`designSystem`, `theme`	Las versiones del sistema de diseño y del tema de Didactika, con la de por defecto de cada uno
`versions[]`	Cada versión de Moodle con su generación de Bootstrap, familia de iconos, soporte y los enlaces a sus `tokens` y `stylesheet`
`resources`	Las direcciones de los componentes, los iconos y la marca
`pages[]`	Cada página: identificador, grupo, orden, sección, versiones, título, resumen, direcciones y los ejemplos que usa
`deepLinks`	Cómo se abre una página en un estado dado

const root = 'https://moodle-design.didactika.org';
const index = await (await fetch(root + '/api/index.json')).json();

if (index.schema !== 1) { throw new Error('Esquema desconocido: ' + index.schema); }
console.log(index.designSystem.default, index.theme.default);   // "0.1" "0.1"
console.log(index.versions.map((v) => v.label));                 // ["Moodle 5.3 LTS", ...]

Estable a propósito

Cada archivo lleva "schema": 1. El número cambia solo cuando se quita un campo o cambia su significado. Añadir campos nunca lo cambia, así que un lector que comprueba el número e ignora lo que no conoce sigue funcionando cuando el sitio crece.
Los identificadores de páginas (bootstrap/buttons) y de ejemplos (buttons/icons) no cambian una vez publicados. Los títulos y resúmenes sí pueden.
Un ejemplo o una página que se quita desaparece de las listas; su dirección antigua deja de responder.
Los datos se regeneran con el sitio. Guárdalos en caché un día, no para siempre, y nunca más tiempo que la versión del sistema de diseño a la que apuntas.

Llamarlo desde otros lenguajes

curl -s https://moodle-design.didactika.org/api/index.json | jq '.pages[] | select(.group == "patterns") | .id'

$root = 'https://moodle-design.didactika.org';
$index = json_decode(file_get_contents($root . '/api/index.json'), true);
foreach ($index['pages'] as $page) {
    echo $page['id'] . ' - ' . $page['title']['es'] . PHP_EOL;
}

import json, urllib.request

root = "https://moodle-design.didactika.org"
with urllib.request.urlopen(root + "/api/components/buttons.json") as response:
    buttons = json.load(response)
print([e["id"] for e in buttons["examples"]])

Buenas maneras

Descarga una vez en tu build, no en cada visita de tu documentación.
Comprueba schema antes de leer e ignora los campos que no conoces.
Conserva la licencia: el sitio y sus datos son GPL-3.0-or-later.