Document federated-api configuration (#121)

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
 

content/api/federated.en.md

@@ -19,6 +19,73 @@ 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. In the vast majority of cases, the default values should be sufficient and only the email sending data should be changed.
+
+```js
+{
+  "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` 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. 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"
+  ]
+}
+```
+
+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 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
+
+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.
+
+- **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": "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"
+  }
+  …
+}
+```
+
+#### Example
+
+```json
+"collections": [
+  "https://opentermsarchive.org/collections.json",
+  {
+    "name": "My Collection",
+    "id": "mycollection",
+    "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.