From 2c87afb21cb06b0d5731c48b1c1374193230ccaa Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Wed, 27 Mar 2024 09:53:30 +0100 Subject: [PATCH 1/7] Document federated-api configuration --- content/api/federated.en.md | 65 +++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/content/api/federated.en.md b/content/api/federated.en.md index a9cb6c9..c1fab0b 100644 --- a/content/api/federated.en.md +++ b/content/api/federated.en.md @@ -19,6 +19,71 @@ This API is offered as a preview, based on a first use case [defined](https://gi The codebase for the Federated API is available on [`github.com/OpenTermsArchive/federated-api`](https://github.com/OpenTermsArchive/federated-api). +## Configuring + +The default configuration can be found in `config/default.json`. The full reference is given below. You are unlikely to want to edit all of these elements. + +```js +{ + "port": "Port number on which the server will listen for incoming connections", + "collections": "Collections configuration key; see below", + "logger": { // Logging mechanism to be notified upon error + "smtp": { + "host": "SMTP server hostname", // Hostname of the SMTP server for sending emails + "username": "User for server authentication" // Password for server authentication is defined in environment variables, see the “Environment variables” section below + }, + "sendMailOnError": { // Can be set to `false` if sending email on error is not needed + "to": "The address to send the email to in case of an error", + "from": "The address from which to send the email", + "sendWarnings": "Boolean. Set to true to also send email in case of warning", + } + }, +} +``` + +The default configuration is merged with (and overridden by) environment-specific configuration that can be specified at startup with the `NODE_ENV` environment variable. See [node-config](https://github.com/node-config/node-config) for more information about configuration files. + +For developement, in order to have a local configuration that override exisiting config, it is recommended to create a `config/development.json` file with overridden values. + +### `collections` configuration key + +The `collections` configuration key is an array containing URLs and directly specified collections. Each item in the collections array can be either a URL pointing to a JSON file containing collections or a directly specified collection object. + +**Structure** + +- **URLs**: URLs pointing to JSON files containing collections description. Each URL should respond with a JSON array containing collection objects. + +- **Directly specified collections**: Collection objects directly specified within the configuration. These collections must include properties: `name`, `id`, and `endpoint`. + +```json +{ + … + { + "name": "The name of the collection", + "id": "A unique identifier for the collection", + "endpoint": "The endpoint or URL where the collection API can be accessed" + } + … +} +``` + +**Example** + +```json +"collections": [ + "https://opentermsarchive.org/collections.json", + { + "name": "Direct Collection", + "id": "directCollection", + "endpoint": "https://domain.example/api" + } +] +``` + +**Conflict Resolution** + +If multiple collections share the same `id`, the latest defined collection in the array will be used and others with the same `id` will be ignored. + ## Deploying Deployment recipes are available in a [dedicated repository](https://github.com/OpenTermsArchive/deployment). Look at the [Federated API section](https://github.com/OpenTermsArchive/deployment#federated-api-application) on the README to know how to deploy the API. From de5934d55b65acd7a2ef55ffbab831d4e991757a Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Wed, 27 Mar 2024 10:14:35 +0100 Subject: [PATCH 2/7] Lint markdown --- content/api/federated.en.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/api/federated.en.md b/content/api/federated.en.md index c1fab0b..183d679 100644 --- a/content/api/federated.en.md +++ b/content/api/federated.en.md @@ -49,7 +49,7 @@ For developement, in order to have a local configuration that override exisiting The `collections` configuration key is an array containing URLs and directly specified collections. Each item in the collections array can be either a URL pointing to a JSON file containing collections or a directly specified collection object. -**Structure** +#### Structure - **URLs**: URLs pointing to JSON files containing collections description. Each URL should respond with a JSON array containing collection objects. @@ -67,7 +67,7 @@ The `collections` configuration key is an array containing URLs and directly spe } ``` -**Example** +#### Example ```json "collections": [ @@ -80,7 +80,7 @@ The `collections` configuration key is an array containing URLs and directly spe ] ``` -**Conflict Resolution** +#### Conflict Resolution If multiple collections share the same `id`, the latest defined collection in the array will be used and others with the same `id` will be ignored. From 08a0acdae0b7d5a0e904ba4ed83cec8ca5d945de Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Wed, 27 Mar 2024 16:38:36 +0530 Subject: [PATCH 3/7] Fix typos --- content/api/federated.en.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/api/federated.en.md b/content/api/federated.en.md index 183d679..a281517 100644 --- a/content/api/federated.en.md +++ b/content/api/federated.en.md @@ -43,7 +43,7 @@ The default configuration can be found in `config/default.json`. The full refere The default configuration is merged with (and overridden by) environment-specific configuration that can be specified at startup with the `NODE_ENV` environment variable. See [node-config](https://github.com/node-config/node-config) for more information about configuration files. -For developement, in order to have a local configuration that override exisiting config, it is recommended to create a `config/development.json` file with overridden values. +For development, in order to have a local configuration that overrides the existing config, it is recommended to create a `config/development.json` file. ### `collections` configuration key From 418ffe82c19994baa49bc1ea05d63720c91dd11b Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Thu, 28 Mar 2024 09:25:47 +0100 Subject: [PATCH 4/7] Improve writing Co-authored-by: Matti Schneider --- content/api/federated.en.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/content/api/federated.en.md b/content/api/federated.en.md index a281517..cca12ef 100644 --- a/content/api/federated.en.md +++ b/content/api/federated.en.md @@ -21,23 +21,25 @@ The codebase for the Federated API is available on [`github.com/OpenTermsArchive ## Configuring -The default configuration can be found in `config/default.json`. The full reference is given below. You are unlikely to want to edit all of these elements. +The default configuration can be found in `config/default.json`. 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. ```js { "port": "Port number on which the server will listen for incoming connections", - "collections": "Collections configuration key; see below", + "collections": [ // Overriding this value creates a risk of splintering the federation, make sure to fully understand what happens when changing this value + "List of collections to federate; see below for how to configure" + ] "logger": { // Logging mechanism to be notified upon error "smtp": { "host": "SMTP server hostname", // Hostname of the SMTP server for sending emails "username": "User for server authentication" // Password for server authentication is defined in environment variables, see the “Environment variables” section below }, - "sendMailOnError": { // Can be set to `false` if sending email on error is not needed + "sendMailOnError": { // Can be set to `false` to disable sending email on error "to": "The address to send the email to in case of an error", "from": "The address from which to send the email", "sendWarnings": "Boolean. Set to true to also send email in case of warning", } - }, + } } ``` @@ -47,20 +49,20 @@ For development, in order to have a local configuration that overrides the exist ### `collections` configuration key -The `collections` configuration key is an array containing URLs and directly specified collections. Each item in the collections array can be either a URL pointing to a JSON file containing collections or a directly specified collection object. +The `collections` configuration key is an array containing URLs or specific collections. Each item in the collections array can be either a URL pointing to a JSON file containing Collections objects, or a Collection object. #### Structure - **URLs**: URLs pointing to JSON files containing collections description. Each URL should respond with a JSON array containing collection objects. -- **Directly specified collections**: Collection objects directly specified within the configuration. These collections must include properties: `name`, `id`, and `endpoint`. +- **Collection objects**: the description of a collection, in the form of an object with required properties: `name`, `id`, and `endpoint`. ```json { … { "name": "The name of the collection", - "id": "A unique identifier for the collection", + "id": "An identifier for the collection that must be unique across the whole federation", "endpoint": "The endpoint or URL where the collection API can be accessed" } … @@ -73,8 +75,8 @@ The `collections` configuration key is an array containing URLs and directly spe "collections": [ "https://opentermsarchive.org/collections.json", { - "name": "Direct Collection", - "id": "directCollection", + "name": "My Collection", + "id": "mycollection", "endpoint": "https://domain.example/api" } ] From dcdfbf231450f15cf4aef7484e4eb923965b783a Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Thu, 28 Mar 2024 09:30:17 +0100 Subject: [PATCH 5/7] Add default values --- content/api/federated.en.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/api/federated.en.md b/content/api/federated.en.md index cca12ef..42d321b 100644 --- a/content/api/federated.en.md +++ b/content/api/federated.en.md @@ -25,9 +25,9 @@ The default configuration can be found in `config/default.json`. The full refere ```js { - "port": "Port number on which the server will listen for incoming connections", + "port": "Port number on which the server will listen for incoming connections. Default: 3333", "collections": [ // Overriding this value creates a risk of splintering the federation, make sure to fully understand what happens when changing this value - "List of collections to federate; see below for how to configure" + "List of collections to federate; see below for how to configure. Default: https://opentermsarchive.org/collections.json" ] "logger": { // Logging mechanism to be notified upon error "smtp": { @@ -37,7 +37,7 @@ The default configuration can be found in `config/default.json`. The full refere "sendMailOnError": { // Can be set to `false` to disable sending email on error "to": "The address to send the email to in case of an error", "from": "The address from which to send the email", - "sendWarnings": "Boolean. Set to true to also send email in case of warning", + "sendWarnings": "Boolean. Set to true to also send email in case of warning. Default: false", } } } From 6e1ea7f90f7b07ea9a5deed956b6a45ac7228b56 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Thu, 28 Mar 2024 09:32:35 +0100 Subject: [PATCH 6/7] Improve writing --- content/_index.en.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/_index.en.md b/content/_index.en.md index 6fcdc34..65713d9 100644 --- a/content/_index.en.md +++ b/content/_index.en.md @@ -345,7 +345,7 @@ The default configuration can be found in `config/default.json`. The full refere The default configuration is merged with (and overridden by) environment-specific configuration that can be specified at startup with the `NODE_ENV` environment variable. See [node-config](https://github.com/node-config/node-config) for more information about configuration files. -In order to have a local configuration that override all exisiting config, it is recommended to create a `config/development.json` file with overridden values. +For development, in order to have a local configuration that overrides the existing config, it is recommended to create a `config/development.json` file. #### Storage repositories From bd42dbf6ab3661bca18d7fc1be16192acb8a9989 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Thu, 28 Mar 2024 09:34:56 +0100 Subject: [PATCH 7/7] Order configuration entries by edit likelihood --- content/api/federated.en.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/api/federated.en.md b/content/api/federated.en.md index 42d321b..8544550 100644 --- a/content/api/federated.en.md +++ b/content/api/federated.en.md @@ -25,10 +25,6 @@ The default configuration can be found in `config/default.json`. The full refere ```js { - "port": "Port number on which the server will listen for incoming connections. Default: 3333", - "collections": [ // Overriding this value creates a risk of splintering the federation, make sure to fully understand what happens when changing this value - "List of collections to federate; see below for how to configure. Default: https://opentermsarchive.org/collections.json" - ] "logger": { // Logging mechanism to be notified upon error "smtp": { "host": "SMTP server hostname", // Hostname of the SMTP server for sending emails @@ -40,6 +36,10 @@ The default configuration can be found in `config/default.json`. The full refere "sendWarnings": "Boolean. Set to true to also send email in case of warning. Default: false", } } + "port": "Port number on which the server will listen for incoming connections. Default: 3333", + "collections": [ // Overriding this value creates a risk of splintering the federation, make sure to fully understand what happens when changing this value + "List of collections to federate; see below for how to configure. Default: https://opentermsarchive.org/collections.json" + ] } ```