Administer Semarchy xDM with the REST API

The Semarchy xDM REST API exposes endpoints to automate the operations required to set up and manage the platform.

Platform administration with REST

The following API endpoints are available for administrative operations:

  • Repository: Create and upgrade repositories, get the platform status and repository information.

  • Execution Engine: Start/Stop the execution engine and retrieve its status.

  • License: Read current license information and upload a new license file.

  • Image Libraries: List available libraries, export and import image libraries content in a zip format.

  • Plugins Bundles: List, delete, import and export bundles containing enricher and validation plugins.

  • Notification Servers and Variable Value Providers: List, get, set or delete the configuration of all or some of these servers.

  • API Keys: Create, delete or update REST API Keys.

  • Configuration: configure the platform and the logging configuration.

  • Custom Translations: Export and import custom translations.

  • REST Clients: Export and import REST client definitions.

  • Identity Management: List, create and update identity management configuration.

  • Users: List, create, update and delete users in the platform.

  • Roles: Retrieve or replace all the roles in the platform.

  • Datasources: Configure the datasources used in the platform.

In addition, probe endpoints are available to monitor the platform, REST API and applications liveliness, startup, and readiness.

Secrets (such as passwords) stored in Semarchy xDM are not included in the response payloads returned by the administration REST API.

Authentication and privileges

Systems or users administrating Semarchy xDM using the REST API must be authenticated.

The Administration REST API supports three authentication methods:

  • Setup Token authentication, where you provide a SetupToken HTTP header containing the value of the Setup Token that is set as an environment variable and is required during the setup or upgrade of Semarchy xDM. This authentication method only gives access to the endpoints for repository setup and upgrade.

  • Basic authentication, where you provide an Authorization HTTP header containing username:password encoded in base64. With this authentication method, REST API calls use the identity, roles, and privileges of the user specified with the username.

  • API Key authentication, where you provide an API-Key HTTP header containing an API key created in Semarchy Configuration. With this authentication method, REST API calls use the identity (default username) and roles defined for the API key.

See Manage roles, API keys, and Secure the data hub for more information about secured access with the REST API.

REST API documentation

The REST API exposes its built-in documentation as a link in the Welcome page. In addition, this documentation is available for tools as an OpenAPI specification.

To access the REST API documentation:

  1. Log in to Semarchy xDM as a user with one of the Application Design, Application Management and Platform Administration platform privileges.

  2. Click the REST API link on the Welcome page.

  3. In the upper-right menu, select Platform Administration.

The documentation exposes the endpoints' descriptions and provides request and response samples.