deploy: 4459f02

api/federation/index.html

@@ -2,7 +2,7 @@
 EN<svg class="icon_arrowDown"><use href="#arrowDown"/></svg></button><div class=languageSwitcher_items><div class=languageSwitcher_item><a href=/fr/>FR</a></div></div></div><ul><li><a class=icon_circle target=_blank rel=noopener href=https://mastodon.lescommuns.org/@opentermsarchive><svg class="icon icon--fill-white"><use href="#mastodon"/></svg></a></li><li><a class=icon_circle target=_blank rel=noopener title="View source code" href=https://github.com/OpenTermsArchive><svg class="icon_github"><use href="#github"/></svg></a></li></ul></nav></div><button type=button class=header_openLink>
 Menu</button>
 <button type=button class=header_closeLink>
-Close<svg class="icon_close"><use href="#close"/></svg></button></header></div></div><div class="container container__hasNoPaddingTop"><div class="container container__1211 container__flex container__hasPaddingYSmall"><aside class=aside><nav class=aside_nav><ul class=aside_items><li class=aside_item><a href=/>Getting started</a></li><li class=aside_item><a href=/navigate-history/>Browsing through terms</a></li><li class=aside_item><a href=/subscribe-rss/>Subscribing to terms changes</a></li><li class=aside_item><a href=/contributing-terms/>Contributing terms</a></li><li class=aside_item><span class=aside_item_section>Collections</span><ul class=aside_subitems><li class=aside_subitem><a href=/collections/metadata/>Metadata</a></li><li class=aside_subitem><a href=/collections/governance/>Governance</a></li><li class=aside_subitem><a href=/collections/create/>Creating a collection</a></li><li class=aside_subitem><a href=/collections/federation/>Federation</a><nav id=TableOfContents><ul><li><a href=#benefits>Benefits</a></li><li><a href=#criteria>Criteria</a></li><li><a href=#how-to-join>How to join</a></li><li><a href=#disclaimer>Disclaimer</a></li></ul></nav></li></ul></li><li class="aside_item aside_item-current"><span class=aside_item_section>API</span><ul class=aside_subitems><li class=aside_subitem><a href=/api/node/>Node</a></li><li class=aside_subitem><a href=/api/collection/>Collection</a></li><li class=aside_subitem><a href=/api/federation/>Federation</a><nav id=TableOfContents><ul><li><a href=#beta>Beta</a></li><li><a href=#source-code>Source code</a></li><li><a href=#configuring>Configuring</a></li><li><a href=#deploying>Deploying</a></li></ul></nav></li></ul></li><li class=aside_item><span class=aside_item_section>Guidelines</span><ul class=aside_subitems><li class=aside_subitem><a href=/guidelines/choosing-selectors/>Choosing selectors</a></li><li class=aside_subitem><a href=/guidelines/declaring/>Declaring documents</a></li><li class=aside_subitem><a href=/guidelines/reviewing/>Reviewing contributions</a></li><li class=aside_subitem><a href=/guidelines/targeting/>Targeting</a></li></ul></li><li class=aside_item><a href=/design-principles/>Design principles</a></li><li class=aside_item><span class=aside_item_section>Memos</span><ul class=aside_subitems><li class=aside_subitem><a href=/memos/writing-reference/>Writing reference</a></li></ul></li></ul></nav></aside><div class=textContent><h1 id=federation-api>Federation API</h1><p>Open Terms Archive is a decentralised system that tracks collections of services&rsquo; terms across multiple servers. Each collection operates its own API, and the Federation API unifies search and discovery across collections, fostering collaboration with external applications.</p><p>The Federation API exposes JSON data over HTTP. Its <a href=http://162.19.74.224/federation-api/v1/docs/>documentation</a> is provided in a dedicated, interactive interface.</p><p>That endpoint exposes both the <a href=https://swagger.io/specification/>OpenAPI</a> specification if the requested <code>Content-Type</code> is JSON, and a Swagger UI for visual and interactive documentation otherwise.</p><h2 id=beta>Beta</h2><p>This API is offered as a preview, based on a first use case <a href=https://github.com/OpenTermsArchive/engine/issues/1016>defined</a> with partner <a href=https://tosdr.org>ToS;DR</a>. Unexpected problems or missing functionality may arise. Please provide feedback through <a href=https://github.com/OpenTermsArchive/federation-api/issues>issues</a> in the dedicated repository.</p><h2 id=source-code>Source code</h2><p>The codebase for the Federation API is available on <a href=https://github.com/OpenTermsArchive/federation-api><code>github.com/OpenTermsArchive/federation-api</code></a>.</p><h2 id=configuring>Configuring</h2><p>The default configuration can be found in <code>config/default.json</code>. The full reference is given below. In the vast majority of cases, the default values should be sufficient and only the email sending data should be changed.</p><div class=highlight><pre tabindex=0 class=chroma><code class=language-js data-lang=js><span class=line><span class=cl><span class=p>{</span>
+Close<svg class="icon_close"><use href="#close"/></svg></button></header></div></div><div class="container container__hasNoPaddingTop"><div class="container container__1211 container__flex container__hasPaddingYSmall"><aside class=aside><nav class=aside_nav><ul class=aside_items><li class=aside_item><a href=/>Getting started</a></li><li class=aside_item><a href=/navigate-history/>Browsing through terms</a></li><li class=aside_item><a href=/subscribe-rss/>Subscribing to terms changes</a></li><li class=aside_item><a href=/contributing-terms/>Contributing terms</a></li><li class=aside_item><span class=aside_item_section>Collections</span><ul class=aside_subitems><li class=aside_subitem><a href=/collections/metadata/>Metadata</a></li><li class=aside_subitem><a href=/collections/governance/>Governance</a></li><li class=aside_subitem><a href=/collections/create/>Creating a collection</a></li><li class=aside_subitem><a href=/collections/federation/>Federation</a><nav id=TableOfContents><ul><li><a href=#benefits>Benefits</a></li><li><a href=#criteria>Criteria</a></li><li><a href=#how-to-join>How to join</a></li><li><a href=#disclaimer>Disclaimer</a></li></ul></nav></li></ul></li><li class="aside_item aside_item-current"><span class=aside_item_section>API</span><ul class=aside_subitems><li class=aside_subitem><a href=/api/node/>Node</a></li><li class=aside_subitem><a href=/api/collection/>Collection</a></li><li class=aside_subitem><a href=/api/federation/>Federation</a><nav id=TableOfContents><ul><li><a href=#beta>Beta</a></li><li><a href=#source-code>Source code</a></li><li><a href=#configuring>Configuring</a></li><li><a href=#deploying>Deploying</a></li></ul></nav></li></ul></li><li class=aside_item><span class=aside_item_section>Guidelines</span><ul class=aside_subitems><li class=aside_subitem><a href=/guidelines/choosing-selectors/>Choosing selectors</a></li><li class=aside_subitem><a href=/guidelines/declaring/>Declaring documents</a></li><li class=aside_subitem><a href=/guidelines/reviewing/>Reviewing contributions</a></li><li class=aside_subitem><a href=/guidelines/targeting/>Targeting</a></li></ul></li><li class=aside_item><a href=/design-principles/>Design principles</a></li><li class=aside_item><span class=aside_item_section>Memos</span><ul class=aside_subitems><li class=aside_subitem><a href=/memos/copywriting-reference/>Copywriting reference</a></li><li class=aside_subitem><a href=/memos/how-to-publish/>How to publish a memo</a></li></ul></li></ul></nav></aside><div class=textContent><h1 id=federation-api>Federation API</h1><p>Open Terms Archive is a decentralised system that tracks collections of services&rsquo; terms across multiple servers. Each collection operates its own API, and the Federation API unifies search and discovery across collections, fostering collaboration with external applications.</p><p>The Federation API exposes JSON data over HTTP. Its <a href=http://162.19.74.224/federation-api/v1/docs/>documentation</a> is provided in a dedicated, interactive interface.</p><p>That endpoint exposes both the <a href=https://swagger.io/specification/>OpenAPI</a> specification if the requested <code>Content-Type</code> is JSON, and a Swagger UI for visual and interactive documentation otherwise.</p><h2 id=beta>Beta</h2><p>This API is offered as a preview, based on a first use case <a href=https://github.com/OpenTermsArchive/engine/issues/1016>defined</a> with partner <a href=https://tosdr.org>ToS;DR</a>. Unexpected problems or missing functionality may arise. Please provide feedback through <a href=https://github.com/OpenTermsArchive/federation-api/issues>issues</a> in the dedicated repository.</p><h2 id=source-code>Source code</h2><p>The codebase for the Federation API is available on <a href=https://github.com/OpenTermsArchive/federation-api><code>github.com/OpenTermsArchive/federation-api</code></a>.</p><h2 id=configuring>Configuring</h2><p>The default configuration can be found in <code>config/default.json</code>. The full reference is given below. In the vast majority of cases, the default values should be sufficient and only the email sending data should be changed.</p><div class=highlight><pre tabindex=0 class=chroma><code class=language-js data-lang=js><span class=line><span class=cl><span class=p>{</span>
 </span></span><span class=line><span class=cl>  <span class=s2>&#34;@opentermsarchive/federation-api&#34;</span><span class=o>:</span> <span class=p>{</span>
 </span></span><span class=line><span class=cl>    <span class=s2>&#34;logger&#34;</span><span class=o>:</span> <span class=p>{</span> <span class=c1>// Logging mechanism to be notified upon error
 </span></span></span><span class=line><span class=cl><span class=c1></span>      <span class=s2>&#34;smtp&#34;</span><span class=o>:</span> <span class=p>{</span>

api/node/index.html

@@ -2,7 +2,7 @@
 EN<svg class="icon_arrowDown"><use href="#arrowDown"/></svg></button><div class=languageSwitcher_items><div class=languageSwitcher_item><a href=/fr/>FR</a></div></div></div><ul><li><a class=icon_circle target=_blank rel=noopener href=https://mastodon.lescommuns.org/@opentermsarchive><svg class="icon icon--fill-white"><use href="#mastodon"/></svg></a></li><li><a class=icon_circle target=_blank rel=noopener title="View source code" href=https://github.com/OpenTermsArchive><svg class="icon_github"><use href="#github"/></svg></a></li></ul></nav></div><button type=button class=header_openLink>
 Menu</button>
 <button type=button class=header_closeLink>
-Close<svg class="icon_close"><use href="#close"/></svg></button></header></div></div><div class="container container__hasNoPaddingTop"><div class="container container__1211 container__flex container__hasPaddingYSmall"><aside class=aside><nav class=aside_nav><ul class=aside_items><li class=aside_item><a href=/>Getting started</a></li><li class=aside_item><a href=/navigate-history/>Browsing through terms</a></li><li class=aside_item><a href=/subscribe-rss/>Subscribing to terms changes</a></li><li class=aside_item><a href=/contributing-terms/>Contributing terms</a></li><li class=aside_item><span class=aside_item_section>Collections</span><ul class=aside_subitems><li class=aside_subitem><a href=/collections/metadata/>Metadata</a></li><li class=aside_subitem><a href=/collections/governance/>Governance</a></li><li class=aside_subitem><a href=/collections/create/>Creating a collection</a></li><li class=aside_subitem><a href=/collections/federation/>Federation</a></li></ul></li><li class="aside_item aside_item-current"><span class=aside_item_section>API</span><ul class=aside_subitems><li class=aside_subitem><a href=/api/node/>Node</a><nav id=TableOfContents><ul><li><a href=#fetch><code>fetch</code></a></li><li><a href=#extract><code>extract</code></a></li><li><a href=#sourcedocument><code>SourceDocument</code></a></li></ul></nav></li><li class=aside_subitem><a href=/api/collection/>Collection</a></li><li class=aside_subitem><a href=/api/federation/>Federation</a></li></ul></li><li class=aside_item><span class=aside_item_section>Guidelines</span><ul class=aside_subitems><li class=aside_subitem><a href=/guidelines/choosing-selectors/>Choosing selectors</a></li><li class=aside_subitem><a href=/guidelines/declaring/>Declaring documents</a></li><li class=aside_subitem><a href=/guidelines/reviewing/>Reviewing contributions</a></li><li class=aside_subitem><a href=/guidelines/targeting/>Targeting</a></li></ul></li><li class=aside_item><a href=/design-principles/>Design principles</a></li><li class=aside_item><span class=aside_item_section>Memos</span><ul class=aside_subitems><li class=aside_subitem><a href=/memos/writing-reference/>Writing reference</a></li></ul></li></ul></nav></aside><div class=textContent><h1 id=nodejs-api-beta>Node.js API [Beta]</h1><p>As a Node module dependency, the engine exposes a JavaScript API that can be called in your own code. The following modules are available.</p><h2 id=fetch><code>fetch</code></h2><p>The <code>fetch</code> module gets the MIME type and content of a document from its URL</p><div class=highlight><pre tabindex=0 class=chroma><code class=language-js data-lang=js><span class=line><span class=cl><span class=kr>import</span> <span class=nx>fetch</span> <span class=nx>from</span> <span class=s1>&#39;@opentermsarchive/engine/fetch&#39;</span><span class=p>;</span>
+Close<svg class="icon_close"><use href="#close"/></svg></button></header></div></div><div class="container container__hasNoPaddingTop"><div class="container container__1211 container__flex container__hasPaddingYSmall"><aside class=aside><nav class=aside_nav><ul class=aside_items><li class=aside_item><a href=/>Getting started</a></li><li class=aside_item><a href=/navigate-history/>Browsing through terms</a></li><li class=aside_item><a href=/subscribe-rss/>Subscribing to terms changes</a></li><li class=aside_item><a href=/contributing-terms/>Contributing terms</a></li><li class=aside_item><span class=aside_item_section>Collections</span><ul class=aside_subitems><li class=aside_subitem><a href=/collections/metadata/>Metadata</a></li><li class=aside_subitem><a href=/collections/governance/>Governance</a></li><li class=aside_subitem><a href=/collections/create/>Creating a collection</a></li><li class=aside_subitem><a href=/collections/federation/>Federation</a></li></ul></li><li class="aside_item aside_item-current"><span class=aside_item_section>API</span><ul class=aside_subitems><li class=aside_subitem><a href=/api/node/>Node</a><nav id=TableOfContents><ul><li><a href=#fetch><code>fetch</code></a></li><li><a href=#extract><code>extract</code></a></li><li><a href=#sourcedocument><code>SourceDocument</code></a></li></ul></nav></li><li class=aside_subitem><a href=/api/collection/>Collection</a></li><li class=aside_subitem><a href=/api/federation/>Federation</a></li></ul></li><li class=aside_item><span class=aside_item_section>Guidelines</span><ul class=aside_subitems><li class=aside_subitem><a href=/guidelines/choosing-selectors/>Choosing selectors</a></li><li class=aside_subitem><a href=/guidelines/declaring/>Declaring documents</a></li><li class=aside_subitem><a href=/guidelines/reviewing/>Reviewing contributions</a></li><li class=aside_subitem><a href=/guidelines/targeting/>Targeting</a></li></ul></li><li class=aside_item><a href=/design-principles/>Design principles</a></li><li class=aside_item><span class=aside_item_section>Memos</span><ul class=aside_subitems><li class=aside_subitem><a href=/memos/copywriting-reference/>Copywriting reference</a></li><li class=aside_subitem><a href=/memos/how-to-publish/>How to publish a memo</a></li></ul></li></ul></nav></aside><div class=textContent><h1 id=nodejs-api-beta>Node.js API [Beta]</h1><p>As a Node module dependency, the engine exposes a JavaScript API that can be called in your own code. The following modules are available.</p><h2 id=fetch><code>fetch</code></h2><p>The <code>fetch</code> module gets the MIME type and content of a document from its URL</p><div class=highlight><pre tabindex=0 class=chroma><code class=language-js data-lang=js><span class=line><span class=cl><span class=kr>import</span> <span class=nx>fetch</span> <span class=nx>from</span> <span class=s1>&#39;@opentermsarchive/engine/fetch&#39;</span><span class=p>;</span>
 </span></span></code></pre></div><p>Documentation on how to use <code>fetch</code> is provided <a href=/jsdoc/index.html>as JSDoc</a>.</p><h3 id=headless-browser-management>Headless browser management</h3><p>If you pass the <code>executeClientScripts</code> option to <code>fetch</code>, a headless browser will be used to download and execute the page before serialising its DOM. For performance reasons, the starting and stopping of the browser is your responsibility to avoid instantiating a browser on each fetch. Here is an example on how to use this feature:</p><div class=highlight><pre tabindex=0 class=chroma><code class=language-js data-lang=js><span class=line><span class=cl><span class=kr>import</span> <span class=nx>fetch</span><span class=p>,</span> <span class=p>{</span> <span class=nx>launchHeadlessBrowser</span><span class=p>,</span> <span class=nx>stopHeadlessBrowser</span> <span class=p>}</span> <span class=nx>from</span> <span class=s1>&#39;@opentermsarchive/engine/fetch&#39;</span><span class=p>;</span>
 </span></span><span class=line><span class=cl>
 </span></span><span class=line><span class=cl><span class=kr>await</span> <span class=nx>launchHeadlessBrowser</span><span class=p>();</span>