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

All systems or users administrating Semarchy xDM through 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 Semarchy xDM’s setup or upgrade. This authentication method grants access only to repository setup and upgrade endpoints.

  • Basic authentication, where you provide an Authorization HTTP header containing the Base64-encoded username:password credentials. 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 (i.e., the default username) and roles defined for the API key.

For more information about secure access with the REST API, see Manage roles, API keys, and Secure the data hub.

REST API documentation

The REST API exposes its built-in documentation as a link on 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 each endpoint’s description and provides request and response samples.