La API JSON

Qué ofrece

La API refleja el árbol de contenido. Las doce tradiciones, los principios destilados de cada una, sus libros fuente, la capa de comparación entre tradiciones, la brújula de unión y el propio estado de revisión del corpus son todos direccionables como JSON. Cuando un documento es prosa extensa, la respuesta lo lleva en markdown en lugar de partirlo en campos que el corpus en realidad no tiene.

Es de solo lectura. Solo se sirve GET, cada respuesta es pública y el contenido está bajo licencia CC BY-SA 4.0.

Ningún endpoint recibe un cuerpo de petición, una cabecera ni un parámetro de consulta — la ruta es toda la petición. La misma URL devuelve siempre los mismos bytes, que es también por lo que el idioma vive en la URL y no en una cabecera.

El sobre

Toda respuesta tiene las mismas tres claves de primer nivel, de modo que un cliente puede tratar igual cualquier endpoint y puede alcanzar todo el árbol conociendo solo la URL raíz.

data

La carga útil, y la única parte cuya forma cambia entre endpoints. Un objeto en la mayoría de ellos; un array en las dos colecciones, que enumeran las tradiciones y los libros fuente de una tradición.

_links

Enlaces con nombre a endpoints relacionados. Cada uno tiene un href y, por lo general, un rel que describe la relación.

• self — la dirección propia de este endpoint, en cada respuesta
• parent — un paso hacia arriba en el árbol
• html — la página legible por humanos que lleva el mismo contenido, en el mismo idioma que la respuesta
• alternate — en la raíz, uno por idioma: la misma API en cada uno de los nueve idiomas, de modo que todo el árbol es alcanzable siguiendo enlaces y no adivinando una URL
• _links — cada entrada de una colección lleva su propio bloque de estos, así que una lista es también un conjunto de direcciones

_meta

Los mismos tres campos en cada respuesta.

• lang — el idioma de este documento — el del árbol del que procede, no un idioma negociado en cada petición
• license — la licencia del contenido, CC BY-SA 4.0
• apiVersion — la versión de la API, actualmente 1.0

La descripción OpenAPI enumera además dos campos opcionales en este objeto, para una etiqueta de entidad y una fecha de última modificación. Hoy nada asigna ninguno de los dos, así que trátalos como ausentes y no como a veces ausentes.

{
  "data": {
    "name": "Cross-Tradition Map",
    "description": "29 convergence themes, 13 held tensions, 41 preserved jewels across 12 traditions.",
    "themeCount": 27,
    "tensionCount": 13,
    "jewelCount": 41
  },
  "_links": {
    "self": {
      "href": "/api/map.json",
      "rel": "self"
    },
    "parent": {
      "href": "/api.json",
      "rel": "parent"
    },
    "convergence": {
      "href": "/api/map/convergence.json",
      "rel": "collection"
    },
    "divergence": {
      "href": "/api/map/divergence.json",
      "rel": "collection"
    },
    "jewels": {
      "href": "/api/map/jewels.json",
      "rel": "collection"
    },
    "html": {
      "href": "/en/map",
      "rel": "alternate",
      "type": "text/html"
    }
  },
  "_meta": {
    "lang": "en",
    "license": "CC BY-SA 4.0",
    "apiVersion": "1.0"
  }
}

Endpoints

Trece formas. Tres de ellas reciben un slug de tradición, y una de esas tres recibe además un identificador de libro, así que hay muchas más URL distintas que filas.

Once de las trece existen también bajo un prefijo de idioma. La última columna indica cuáles, y la sección sobre idiomas de más abajo explica qué te da eso y qué no.

No se sirve nada más bajo esta ruta. Si un endpoint no figura aquí, no existe, y el índice raíz es la autoridad — solo enlaza a endpoints que resuelven.

Probarla

El índice raíz es el lugar por donde empezar — es pequeño, y todos los demás endpoints cuelgan de él, incluida la raíz de cada idioma.

curl -s https://distill.family/api.json

Descripción OpenAPI

Un documento OpenAPI 3.1 describe todos los endpoints anteriores, junto con los esquemas del sobre y de los enlaces. Apunta un generador hacia él, o simplemente léelo.

/api/openapi.json

Los endpoints con prefijo de idioma se escriben uno por idioma en lugar de dejarse como plantilla. Un cliente generado no puede sustituir en una plantilla para la que no tiene lista, y la comprobación de compilación que afirma que toda ruta documentada resuelve de verdad tampoco puede seguir una — así que enumerarlos mantiene todo el árbol localizado bajo esa afirmación.

Deliberadamente no se muestra aquí en un explorador interactivo. Este sitio envía una política de seguridad de contenido que permite scripts, estilos y conexiones de red solo desde su propio origen, y todos los exploradores se cargan desde otro sitio — así que incrustar uno fallaría en silencio o supondría debilitar esa política para todos los visitantes. Descarga el documento y ábrelo en una herramienta en la que ya confíes.

Idiomas

Hay dos árboles que sirven los mismos endpoints. El canónico es el inglés. El otro lleva un prefijo de idioma y se construye una vez por cada uno de los nueve idiomas que admite el sitio.

/api/es.json

El idioma es un segmento de la ruta, no una negociación. No se lee ningún parámetro de consulta y no se lee la cabecera Accept-Language — y eso es una decisión de diseño, no una omisión. Todos los endpoints se prerrenderizan: el manejador se ejecuta una vez en tiempo de construcción, sin ninguna petición contra la que negociar, y el archivo resultante se sirve luego a todo el mundo. Una respuesta que no puede variar según una cabecera tiene que llevar su idioma en la URL, donde es direccionable, enlazable y almacenable en caché.

Un segmento de idioma que no sea uno de los nueve devuelve 404. Sería peor servir inglés bajo la URL de otro idioma y dejar que una capa de caché lo mantuviera ahí — todo el sentido de poner el idioma en la ruta es que la dirección diga la verdad sobre lo que ha llegado.

Hay una segunda razón para validarlo. Lo que devuelve el resolutor de idioma se usa para construir una ruta del sistema de archivos cuando se lee el corpus, de modo que un valor tomado directamente de una petición sería una manera de pedir archivos fuera del árbol de contenido. El resolutor comprueba contra la lista cerrada de idiomas admitidos antes de devolver nada, así que no puede emitir un segmento que no sea uno de ellos, se le llame como se le llame. El 404 de arriba es cuestión de honestidad; esta parte es la que trata de la seguridad.

Una capa no está traducida en absoluto. Los libros fuente individuales están en inglés en todas partes, porque no existe ninguna traducción de ellos — así que esos endpoints se sirven solo desde el árbol inglés, y una colección de libros con prefijo de idioma enlaza cada entrada de vuelta al documento en inglés, que declara eso mismo sobre sí mismo.

En lo demás, la traducción es por documento y no por árbol. Cada respuesta lleva un indicador que dice si el documento que contiene fue traducido, y un documento sin traducción en ese idioma recurre al inglés en lugar de no devolver nada. Así que lee el indicador, no la URL.

Y lee ese indicador en sentido estricto. Registra que existe una traducción y que no se perdió nada portante en ella — se comprueba la presencia de encabezados, citas textuales, referencias y términos preservados. No registra que la traducción sea exacta. Ningún hablante nativo ha revisado nada de este corpus. Un documento traducido conviene tomarlo como una versión utilizable, no como texto verificado, y el endpoint raíz lo dice en su propia respuesta en lugar de dejar que un cliente lo descubra.

Cabeceras y caché

Se permiten peticiones de origen cruzado desde cualquier host, así que una página servida desde cualquier sitio puede obtenerlas directamente. Solo se anuncian GET y OPTIONS.

Las respuestas se pueden guardar en caché cinco minutos en un navegador y una hora en una caché compartida. Son archivos estáticos tras un servidor de archivos estáticos, que envía con cada uno una etiqueta de entidad débil, de modo que las peticiones condicionales funcionan.

Usarla

El contenido destilado se publica bajo licencia Creative Commons Atribución-CompartirIgual 4.0 (se abre en una pestaña nueva). Úsalo, cítalo, construye sobre él — atribuye a Distill.family y publica lo que construyas con la misma licencia. Las citas de las escrituras proceden de ediciones de dominio público, atribuidas en línea donde se recurrió a una traducción concreta.

Dos cosas que llevar junto con los datos. Las citas están verificadas carácter por carácter frente a esas ediciones, pero ningún especialista desde dentro de ninguna de las doce tradiciones ha dado el visto bueno a estas lecturas; el endpoint de estado de la revisión informa exactamente de en qué punto está eso, tradición por tradición.

Y el punto de vista es asumido, no neutral. Aquí las tradiciones se tratan como visiones parciales potencialmente complementarias, cosa que la mayoría de ellas rechaza. Cualquier cosa construida sobre estos datos hereda esa elección, así que es mejor reafirmarla que transmitirla en silencio.