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 diff --git a/content/api/federated.en.md b/content/api/federated.en.md index a9cb6c9..8544550 100644 --- a/content/api/federated.en.md +++ b/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.