JSON API

它提供什么

这套 API 是内容树的镜像。十二个传统、从每一个传统萃取出的原则、它们的源典、跨传统的比较层、并集罗盘，以及语料自身的审阅状态，全都可以作为 JSON 寻址。凡文档为长篇散文之处，响应以 markdown 承载它，而不是把它切分成语料实际上并不具备的字段。

它是只读的。只提供 GET，每一份响应都是公开的，内容依据 CC BY-SA 4.0 授权。

没有任何端点接受请求体、请求头或查询参数——路径就是整个请求。同一个 URL 始终返回同样的字节，这也是语言存在于 URL 之中而非请求头之中的原因。

响应信封

每一份响应都有相同的三个顶层键，因此客户端可以用同一种方式对待任何端点，并且只需知道根 URL 就能抵达整棵树。

data

载荷，也是各端点之间唯一会改变形状的部分。在多数端点上是一个对象；在两个集合端点上是一个数组，它们分别列出诸传统与某一传统的源典。

_links

指向相关端点的具名链接。每一项都有一个 href，通常还有一个描述该关系的 rel。

• self — 该端点自身的地址，出现在每一份响应上
• parent — 沿树回退一步
• html — 承载同样内容的人类可读页面，与响应同为一种语言
• alternate — 在根端点上，每种语言一个：同一套 API 在九种语言中的各自版本，因此整棵树都可以通过跟随链接抵达，而不必猜测某个 URL
• _links — 集合中的每一条目都带有自己的一组这样的链接，因此一份列表同时也是一组地址

_meta

每一份响应上都相同的那三个字段。

• lang — 本文档的语言——它所来自的那棵树的语言，而不是按请求协商出来的语言
• license — 内容的许可协议，CC BY-SA 4.0
• apiVersion — API 版本，当前为 1.0

OpenAPI 描述还在这个对象上列出了两个可选字段，分别用于一个实体标签与一个最后修改日期。目前没有任何东西为它们中的任何一个赋值，因此请把两者都视为不存在，而不是「有时缺失」。

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

端点

十三种形态。其中三种接受一个传统 slug，而这三种里又有一种还接受一个典籍标识符，因此不同 URL 的数量远多于表格的行数。

十三种中有十一种同时存在于语言前缀之下。最后一列标明是哪些；下方关于语言的一节说明这能给你什么、又不能给你什么。

此路径之下不提供任何别的东西。若某个端点未列于此，它就不存在；根索引是权威所在——它只链接到能够解析的端点。

试用

根索引是起点——它很小，而其他每一个端点都挂在它下面，包括每种语言各自的根。

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

OpenAPI 描述

一份 OpenAPI 3.1 文档描述了以上每一个端点，连同信封与链接的模式。把生成器指向它，或者干脆就读它。

/api/openapi.json

带语言前缀的端点是逐个语言写出的，而不是留作一个模板。生成的客户端无法向一个自己没有清单的模板中代入值；而那项断言每一条被记录的路径确实可以解析的构建检查，同样无法跟随模板——因此把它们逐一列举出来，能让整棵本地化的树都处在那项断言之下。

这里刻意没有用交互式浏览工具把它渲染出来。本站发送的内容安全策略只允许来自自身源的脚本、样式与网络连接，而那些浏览工具全都从别处加载——所以嵌入其中任何一个，要么会静默失败，要么意味着为每一位访客削弱那项策略。请取回该文档，并在你已经信任的工具中打开它。

语言

有两棵树提供同样的端点。规范的那一棵是英文。另一棵带有语言前缀，并为本站支持的九种语言各构建一次。

/api/es.json

语言是一个路径段，而不是一次协商。查询参数不会被读取，Accept-Language 请求头也不会被读取——这是一项设计决定，而不是一处疏漏。每一个端点都经过预渲染：处理程序在构建时运行一次，那时并没有可供协商的请求，生成的文件随后被提供给所有人。一份无法随请求头而变化的响应，只能把自己的语言承载在 URL 里——在那里它可被寻址、可被链接、可被缓存。

不属于这九种之一的语言段返回 404。在另一种语言的 URL 之下提供英文、并任由缓存层把它留在那里，会更糟——把语言放进路径的全部意义，就在于地址如实说出返回的是什么。

对它加以校验还有第二个理由。读取语料时，语言解析器返回的值会被用来构造文件系统路径，因此一个直接取自请求的值，就成了索取内容树之外文件的一条途径。解析器在返回任何东西之前，都会对照受支持语言的封闭清单进行检查，所以无论怎样调用它，它都不可能吐出不在清单中的语言段。上面那个 404 关乎诚实；这一部分关乎安全。

有一层完全没有翻译。各部源典在任何语言下都是英文，因为它们并不存在译本——所以那些端点只从英文树提供；带语言前缀的典籍集合会把每一条目链接回英文文档，而该文档自身也如此报告。

其余之处，翻译是逐文档而非逐树进行的。每一份响应都带有一个标志，说明它所承载的文档是否已被翻译；在某种语言中没有译本的文档会回退到英文，而不是什么都不返回。因此请读那个标志，而不是 URL。

而且要严格地读那个标志。它记录的是：存在一份译文，且其中没有丢失任何承重之物——标题、引文、出处标注、所保留的术语，全都做过在场检查。它并不记录译文是准确的。没有任何母语者读过这份语料的任何部分。一份译过的文档最好被当作可用的呈现，而不是经过验证的文本；根端点在自己的响应里就如此说明，而不是把这件事留给客户端自己去发现。

请求头与缓存

允许来自任何主机的跨源请求，因此在任何地方提供的页面都可以直接抓取这些内容。只声明 GET 与 OPTIONS。

响应在浏览器中可缓存五分钟，在共享缓存中可缓存一小时。它们是静态文件服务器背后的静态文件，服务器会为每一份附上一个弱实体标签，因此条件请求可以工作。

使用

萃取出的内容依据 知识共享署名-相同方式共享 4.0 （在新标签页中打开） 授权。使用它、引用它、在它之上构建——请署名 Distill.family，并以同样的方式为你所构建的东西授权。经文引用取自公有领域的版本；凡依赖了某个特定译本之处，均随文标注。

有两件事需要与数据一同带走。引文已对照那些版本逐字核验，但十二个传统中，没有任何一位来自传统内部的学者为这些读法背书；审阅状态端点会逐个传统地准确报告这件事的进展。

而且这一立场是被承担的，并非中立。诸传统在此被当作可能互补的局部视角来对待，而它们大多数拒绝这一点。任何建立在这份数据之上的东西都继承了这个选择，因此把它重新说明出来，胜过默默地把它传下去。