Die JSON-API

Was sie ausliefert

Die API spiegelt den Inhaltsbaum. Die zwölf Traditionen, die aus jeder destillierten Prinzipien, ihre Quellentexte, die traditionsübergreifende Vergleichsebene, der Kompass der Vereinigung und der Stand der Begutachtung des Korpus selbst sind alle als JSON adressierbar. Wo ein Dokument längere Prosa ist, trägt die Antwort es als Markdown, statt es in Felder zu zerlegen, die der Korpus in Wirklichkeit nicht hat.

Sie ist nur lesend. Nur GET wird ausgeliefert, jede Antwort ist öffentlich, und der Inhalt steht unter der Lizenz CC BY-SA 4.0.

Kein Endpunkt nimmt einen Anfragekörper, einen Header oder einen Query-Parameter — der Pfad ist die ganze Anfrage. Dieselbe URL liefert immer dieselben Bytes zurück, weshalb auch die Sprache in der URL steht und nicht in einem Header.

Der Umschlag

Jede Antwort hat dieselben drei Schlüssel auf oberster Ebene, sodass ein Client jeden Endpunkt gleich behandeln und den ganzen Baum erreichen kann, wenn er nur die Wurzel-URL kennt.

data

Die Nutzlast, und der einzige Teil, dessen Form sich zwischen den Endpunkten ändert. Bei den meisten ein Objekt; bei den beiden Sammlungen ein Array, die die Traditionen und die Quellentexte einer Tradition auflisten.

_links

Benannte Links auf verwandte Endpunkte. Jeder hat ein href und meist ein rel, das die Beziehung beschreibt.

• self — die eigene Adresse dieses Endpunkts, bei jeder Antwort
• parent — einen Schritt zurück den Baum hinauf
• html — die menschenlesbare Seite mit demselben Inhalt, in derselben Sprache wie die Antwort
• alternate — an der Wurzel, einer pro Sprache: dieselbe API in jeder der neun Sprachen, sodass der ganze Baum durch Folgen von Links erreichbar ist statt durch Raten einer URL
• _links — jeder Eintrag einer Sammlung trägt seinen eigenen Block davon, sodass eine Liste zugleich eine Menge von Adressen ist

_meta

Dieselben drei Felder bei jeder Antwort.

• lang — die Sprache dieses Dokuments — die des Baums, aus dem es stammt, keine pro Anfrage ausgehandelte Sprache
• license — die Lizenz des Inhalts, CC BY-SA 4.0
• apiVersion — die API-Version, derzeit 1.0

Die OpenAPI-Beschreibung führt an diesem Objekt außerdem zwei optionale Felder auf, für ein Entity-Tag und ein Datum der letzten Änderung. Heute setzt nichts eines von beiden, behandeln Sie sie also als abwesend und nicht als manchmal fehlend.

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

Endpunkte

Dreizehn Formen. Drei davon nehmen einen Traditions-Slug, und eine dieser drei nimmt zusätzlich eine Buchkennung, sodass es weit mehr verschiedene URLs als Zeilen gibt.

Elf der dreizehn gibt es auch unter einem Sprachpräfix. Die letzte Spalte sagt, welche, und der Abschnitt zu den Sprachen weiter unten sagt, was Ihnen das bringt und was nicht.

Unter diesem Pfad wird nichts weiter ausgeliefert. Ein Endpunkt, der hier nicht aufgeführt ist, existiert nicht, und maßgeblich ist der Wurzelindex — er verlinkt nur auf Endpunkte, die auch auflösen.

Ausprobieren

Der Wurzelindex ist der Anfang — er ist klein, und jeder andere Endpunkt hängt daran, einschließlich der Wurzel jeder Sprache.

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

OpenAPI-Beschreibung

Ein OpenAPI-3.1-Dokument beschreibt jeden Endpunkt oben, zusammen mit den Schemata für Umschlag und Links. Richten Sie einen Generator darauf, oder lesen Sie es einfach.

/api/openapi.json

Die sprachpräfigierten Endpunkte sind Sprache für Sprache ausgeschrieben, statt als Vorlage stehen zu bleiben. Ein erzeugter Client kann nicht in eine Vorlage einsetzen, für die er keine Liste hat, und die Bauprüfung, die feststellt, dass jeder dokumentierte Pfad wirklich auflöst, kann einer solchen ebenso wenig folgen — sie auszuschreiben hält daher den ganzen lokalisierten Baum unter dieser Feststellung.

Sie wird hier bewusst nicht in einem interaktiven Explorer dargestellt. Diese Website sendet eine Content-Security-Policy, die Skripte, Stile und Netzwerkverbindungen nur von ihrem eigenen Ursprung erlaubt, und die Explorer laden alle von woanders — einen einzubinden würde also entweder still fehlschlagen oder bedeuten, diese Richtlinie für jeden Besucher zu schwächen. Holen Sie sich das Dokument und öffnen Sie es in einem Werkzeug, dem Sie ohnehin vertrauen.

Sprachen

Es gibt zwei Bäume, die dieselben Endpunkte ausliefern. Der kanonische ist der englische. Der andere trägt ein Sprachpräfix und wird für jede der neun Sprachen, die die Website unterstützt, einmal gebaut.

/api/es.json

Die Sprache ist ein Pfadsegment, keine Aushandlung. Ein Query-Parameter wird nicht gelesen und der Accept-Language-Header wird nicht gelesen — und das ist eine Entwurfsentscheidung, kein Versäumnis. Jeder Endpunkt wird vorgerendert: Der Handler läuft einmal zur Bauzeit, ohne eine Anfrage, gegen die sich aushandeln ließe, und die entstandene Datei wird dann an alle ausgeliefert. Eine Antwort, die nicht nach Header variieren kann, muss ihre Sprache in der URL tragen, wo sie adressierbar, verlinkbar und zwischenspeicherbar ist.

Ein Sprachsegment, das keine der neun ist, liefert 404. Es wäre schlimmer, Englisch unter der URL einer anderen Sprache auszuliefern und es von einer Cache-Schicht dort halten zu lassen — der ganze Sinn der Sprache im Pfad ist, dass die Adresse die Wahrheit über das sagt, was zurückkam.

Es gibt einen zweiten Grund, es zu prüfen. Was der Sprachauflöser zurückgibt, wird beim Lesen des Korpus zu einem Dateisystempfad zusammengesetzt, sodass ein direkt aus einer Anfrage übernommener Wert ein Weg wäre, Dateien außerhalb des Inhaltsbaums anzufordern. Der Auflöser prüft gegen die geschlossene Liste der unterstützten Sprachen, bevor er irgendetwas zurückgibt, und kann daher kein Segment ausgeben, das nicht darin steht, wie auch immer er aufgerufen wird. Beim 404 oben geht es um Ehrlichkeit; hier geht es um Sicherheit.

Eine Ebene ist überhaupt nicht übersetzt. Die einzelnen Quellentexte sind überall englisch, weil keine Übersetzung von ihnen existiert — diese Endpunkte werden daher nur aus dem englischen Baum ausgeliefert, und eine sprachpräfigierte Buchsammlung verweist jeden Eintrag zurück auf das englische Dokument, das eben dies über sich selbst meldet.

Ansonsten wird pro Dokument übersetzt, nicht pro Baum. Jede Antwort trägt ein Kennzeichen, das sagt, ob das enthaltene Dokument übersetzt wurde, und ein Dokument ohne Übersetzung in dieser Sprache fällt auf Englisch zurück, statt nichts zurückzugeben. Lesen Sie also das Kennzeichen, nicht die URL.

Und lesen Sie dieses Kennzeichen eng. Es hält fest, dass eine Übersetzung existiert und dass nichts Tragendes daraus verloren ging — Überschriften, Zitate, Belege und bewahrte Begriffe werden alle auf Anwesenheit geprüft. Es hält nicht fest, dass die Übersetzung zutreffend ist. Kein Muttersprachler hat irgendetwas an diesem Korpus geprüft. Ein übersetztes Dokument nimmt man am besten als brauchbare Wiedergabe, nicht als verifizierten Text, und der Wurzel-Endpunkt sagt das in seiner eigenen Antwort, statt es einen Client herausfinden zu lassen.

Header und Caching

Ursprungsübergreifende Anfragen sind von jedem Host aus erlaubt, sodass eine von irgendwo ausgelieferte Seite diese direkt abrufen kann. Angekündigt werden nur GET und OPTIONS.

Antworten sind fünf Minuten im Browser und eine Stunde in einem geteilten Cache zwischenspeicherbar. Es sind statische Dateien hinter einem Server für statische Dateien, der zu jeder ein schwaches Entity-Tag mitsendet, sodass bedingte Anfragen funktionieren.

Verwenden

Die destillierten Inhalte stehen unter der Lizenz Creative Commons Namensnennung-Weitergabe unter gleichen Bedingungen 4.0 (öffnet in einem neuen Tab). Nutzen Sie sie, zitieren Sie sie, bauen Sie darauf auf — nennen Sie Distill.family, und stellen Sie das Gebaute unter dieselbe Lizenz. Die Schriftzitate stammen aus gemeinfreien Ausgaben, im Text nachgewiesen, wo eine bestimmte Übersetzung herangezogen wurde.

Zwei Dinge, die mit den Daten mitzunehmen sind. Die Zitate sind Zeichen für Zeichen gegen jene Ausgaben verifiziert, aber kein Fachkundiger aus dem Inneren einer der zwölf Traditionen hat diese Lesarten abgenommen; der Endpunkt zum Stand der Begutachtung berichtet Tradition für Tradition genau, wie es darum steht.

Und der Standpunkt ist eingestanden, nicht neutral. Die Traditionen werden hier als möglicherweise einander ergänzende Teilansichten behandelt, was die meisten von ihnen ablehnen. Alles, was auf diesen Daten aufbaut, erbt diese Entscheidung, und es ist besser, sie erneut zu benennen, als sie stillschweigend weiterzugeben.