Configuration

Configure your App in Ergonode

If the App requires configuration and defines configuration form in configuration_schema it has to appropriately handle the values.

It has to be able to validate and persist the configuration and also provide the configuration for reading.

To do so 2 endpoints implementation is necessary.

Each endpoint receives an appropriate X-APP-TOKEN HTTP header with JWT that allows authentication of the caller.

[GET] /configuration

The endpoint should return all so-far persisted schemas in update configuration steps in the form of an array of data - according to your schema.

For example for a simple configuration schema

{
  "configuration_schema": [
    {
      "title": "Connection",
      "type": "object",
      "properties": {
        "token": {
          "type": "string",
          "title": "API token",
          "widget": "password",
          "propertyOrder": 1
        }
      },
      "required": [
        "token"
      ]
    },
    {
      "title": "Settings",
      "type": "object",
      "properties": {
        "setting1": {
          "type": "string",
          "title": "setting 1",
          "propertyOrder": 1
        },
        "setting2": {
          "type": "string",
          "title": "setting 2",
          "propertyOrder": 1
        }
      },
      "required": [
        "text"
      ]
    }
  ]
}

the expected response would be

[
  {
    "token": "secret API token"
  },
  {
    "setting1": "user input text 1",
    "setting2": "user input text 2"
  }
]

Every object represents single form step/one configuration schema.

Preserving the configured objects under the same indexes as their definitions in the configuration schema is mandatory.

[POST] /configuration

The endpoint accepts, validates, and persists in the configuration step.

payload

Example

{
  "index": 0,
  "configuration": {
    "text": "user input text"
  }
}

Schema

{
  "type": "object",
  "properties": {
    "index": {
      "type": "integer",
      "description": "The index of the configuration step from configuration schema."
    },
    "configuration": {
      "type": "object",
      "description": "The form data according to configuration schema."
    }
  },
  "required": [
    "index",
    "configuration"
  ]
}

All 2xx responses will be treated as success.

Error handling

The forms are validated against configuration schema but not all validation can be performed based on JSON schema.

I.e. API token can only be verified in the App.

Though the frontend application performs configuration validation on every step it is a good practice to perform full validation in the App as well to limit any potential errors.

To assign a custom error message to specific user form fields it is required to return an error response with code 422 and the payload

Example

{
  "title": "Form validation errors.",
  "detail": "Token for API is not valid",
  "violations": [
    {
      "propertyPath": "token",
      "title": "Token for API is not valid",
      "template": "Token for %parameter% is not valid",
      "parameters": {
        "%parameter%": "API"
      }
    }
  ]
}

Schema

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "The title of an error."
    },
    "detail": {
      "type": "string",
      "description": "Detailed errors description."
    },
    "violations": {
      "type": "array",
      "description": "The list of violations.",
      "items": {
        "type": "object",
        "properties": {
          "propertyPath": {
            "type": "string",
            "description": "Path to the field the violation applies"
          },
          "title": {
            "type": "string",
            "description": "Ready to use message"
          },
          "template": {
            "type": "string",
            "description": "Template of the message"
          },
          "parameters": {
            "type": "object",
            "description": "Parameters of the template"
          }
        }
      }
    }
  },
  "required": [
    "index",
    "configuration"
  ]
}

All other error codes will be treated with a generic error message.