L'API JSON

Ce qu'elle fournit

L'API reflète l'arbre de contenu. Les douze traditions, les principes distillés de chacune, leurs livres sources, la couche de comparaison inter-traditions, la boussole d'union et l'état de relecture du corpus lui-même sont tous adressables en JSON. Là où un document est de la prose longue, la réponse le porte en markdown plutôt que de le découper en champs que le corpus n'a pas réellement.

Elle est en lecture seule. Seul GET est servi, chaque réponse est publique, et le contenu est sous licence CC BY-SA 4.0.

Aucun point de terminaison ne prend de corps de requête, d'en-tête ni de paramètre de requête — le chemin est toute la requête. La même URL renvoie toujours les mêmes octets, ce qui explique aussi pourquoi la langue vit dans l'URL plutôt que dans un en-tête.

L'enveloppe

Chaque réponse a les mêmes trois clés de premier niveau, si bien qu'un client peut traiter n'importe quel point de terminaison de la même façon et atteindre tout l'arbre en ne connaissant que l'URL racine.

data

La charge utile, et la seule partie dont la forme change d'un point de terminaison à l'autre. Un objet sur la plupart d'entre eux ; un tableau sur les deux collections, qui listent les traditions et les livres sources d'une tradition.

_links

Des liens nommés vers des points de terminaison apparentés. Chacun a un href, et le plus souvent un rel décrivant la relation.

• self — l'adresse propre de ce point de terminaison, sur chaque réponse
• parent — un cran plus haut dans l'arbre
• html — la page lisible par un humain qui porte le même contenu, dans la même langue que la réponse
• alternate — sur la racine, un par langue : la même API dans chacune des neuf langues, de sorte que tout l'arbre est accessible en suivant des liens plutôt qu'en devinant une URL
• _links — chaque entrée d'une collection porte son propre bloc de ces liens, si bien qu'une liste est aussi un ensemble d'adresses

_meta

Les mêmes trois champs sur chaque réponse.

• lang — la langue de ce document — celle de l'arbre dont il provient, non une langue négociée à chaque requête
• license — la licence du contenu, CC BY-SA 4.0
• apiVersion — la version de l'API, actuellement 1.0

La description OpenAPI liste aussi deux champs facultatifs sur cet objet, pour une étiquette d'entité et une date de dernière modification. Aujourd'hui rien ne renseigne ni l'un ni l'autre : traitez-les donc comme absents plutôt que comme parfois manquants.

{
  "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"
  }
}

Points de terminaison

Treize formes. Trois d'entre elles prennent un slug de tradition, et l'une de ces trois prend en plus un identifiant de livre, si bien qu'il y a beaucoup plus d'URL distinctes que de lignes.

Onze des treize existent aussi sous un préfixe de langue. La dernière colonne indique lesquels, et la section sur les langues plus bas dit ce que cela vous donne et ce que cela ne vous donne pas.

Rien d'autre n'est servi sous ce chemin. Si un point de terminaison ne figure pas ici, il n'existe pas, et l'index racine fait autorité — il ne renvoie qu'à des points de terminaison qui aboutissent.

L'essayer

L'index racine est le point de départ — il est petit, et tous les autres points de terminaison en dépendent, y compris la racine de chaque langue.

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

Description OpenAPI

Un document OpenAPI 3.1 décrit chacun des points de terminaison ci-dessus, ainsi que les schémas de l'enveloppe et des liens. Pointez un générateur dessus, ou lisez-le simplement.

/api/openapi.json

Les points de terminaison préfixés par une langue sont écrits une langue à la fois plutôt que laissés sous forme de gabarit. Un client généré ne peut pas faire de substitution dans un gabarit dont il n'a pas la liste, et le contrôle de construction qui affirme que chaque chemin documenté aboutit réellement ne peut pas en suivre un non plus — les énumérer maintient donc tout l'arbre localisé sous cette affirmation.

Elle n'est délibérément pas rendue ici dans un explorateur interactif. Ce site envoie une politique de sécurité du contenu qui n'autorise scripts, styles et connexions réseau que depuis sa propre origine, et les explorateurs se chargent tous d'ailleurs — en intégrer un échouerait donc silencieusement ou obligerait à affaiblir cette politique pour chaque visiteur. Récupérez le document et ouvrez-le dans un outil auquel vous faites déjà confiance.

Langues

Deux arbres servent les mêmes points de terminaison. Le canonique est l'anglais. L'autre porte un préfixe de langue et est construit une fois pour chacune des neuf langues que le site prend en charge.

/api/es.json

La langue est un segment de chemin, non une négociation. Aucun paramètre de requête n'est lu et l'en-tête Accept-Language n'est pas lu — et c'est une décision de conception, non un oubli. Chaque point de terminaison est prérendu : le gestionnaire s'exécute une fois au moment de la construction, sans requête contre laquelle négocier, et le fichier obtenu est ensuite servi à tout le monde. Une réponse qui ne peut pas varier selon un en-tête doit porter sa langue dans l'URL, où elle peut être adressée, liée et mise en cache.

Un segment de langue qui n'est pas l'une des neuf renvoie 404. Il serait pire de servir de l'anglais sous l'URL d'une autre langue et de laisser une couche de cache l'y conserver — tout l'intérêt de mettre la langue dans le chemin est que l'adresse dise la vérité sur ce qui est revenu.

Il y a une seconde raison de le valider. Ce que renvoie le résolveur de langue sert à construire un chemin de système de fichiers lors de la lecture du corpus : une valeur reprise telle quelle d'une requête serait donc un moyen de demander des fichiers hors de l'arbre de contenu. Le résolveur la vérifie contre la liste fermée des langues prises en charge avant de renvoyer quoi que ce soit, et il ne peut donc pas produire un segment qui n'en fait pas partie, quelle que soit la façon dont il est appelé. Le 404 ci-dessus relève de l'honnêteté ; ceci relève de la sécurité.

Une couche n'est pas traduite du tout. Les livres sources pris un à un sont en anglais partout, parce qu'il n'en existe aucune traduction — ces points de terminaison ne sont donc servis que depuis l'arbre anglais, et une collection de livres préfixée par une langue renvoie chaque entrée vers le document anglais, qui le déclare lui-même.

Pour le reste, la traduction se fait par document et non par arbre. Chaque réponse porte un indicateur disant si le document qu'elle contient a été traduit, et un document sans traduction dans cette langue retombe sur l'anglais plutôt que de ne rien renvoyer. Lisez donc l'indicateur, non l'URL.

Et lisez cet indicateur au sens strict. Il consigne qu'une traduction existe et que rien de porteur n'en a été perdu — titres, citations, références et termes préservés sont tous contrôlés quant à leur présence. Il ne consigne pas que la traduction est exacte. Aucun locuteur natif n'a relu quoi que ce soit de ce corpus. Mieux vaut tenir un document traduit pour un rendu utilisable, non pour un texte vérifié, et le point de terminaison racine le dit dans sa propre réponse plutôt que de laisser un client le découvrir.

En-têtes et mise en cache

Les requêtes multi-origines sont autorisées depuis n'importe quel hôte : une page servie de n'importe où peut donc les récupérer directement. Seuls GET et OPTIONS sont annoncés.

Les réponses sont conservables en cache cinq minutes dans un navigateur et une heure dans un cache partagé. Ce sont des fichiers statiques derrière un serveur de fichiers statiques, qui envoie avec chacun une étiquette d'entité faible, de sorte que les requêtes conditionnelles fonctionnent.

L'utiliser

Le contenu distillé est placé sous licence Creative Commons Attribution-Partage dans les Mêmes Conditions 4.0 (s'ouvre dans un nouvel onglet). Utilisez-le, citez-le, construisez dessus — attribuez à Distill.family, et placez ce que vous construisez sous la même licence. Les citations d'écritures proviennent d'éditions du domaine public, attribuées en ligne là où une traduction précise a été utilisée.

Deux choses à emporter avec les données. Les citations sont vérifiées caractère par caractère face à ces éditions, mais aucun spécialiste interne à l'une des douze traditions n'a validé ces lectures ; le point de terminaison d'état de la relecture indique exactement où en est cette question, tradition par tradition.

Et le point de vue est assumé, non neutre. Les traditions sont traitées ici comme des vues partielles potentiellement complémentaires, ce que la plupart d'entre elles rejettent. Tout ce qui est construit sur ces données hérite de ce choix : mieux vaut le redire que le transmettre en silence.