REST API Integration
The REST API provides programmatic access to consume, certify, and publish data in a data hub.
The REST API is available at the following base URL (referred to as
Each operation in the REST API is available with a parameterized URL under this base URL. The URL may also take additional parameters.
URL parameters names are case sensitive. Make sure to use them with the case described in this documentation. For example
REST API Readiness
The REST API exposes probe endpoints (
/api/rest/probes/) to monitor the platform, REST API and applications liveliness, startup, and readiness.
These endpoints do not require authentication.
The REST API readiness endpoint (
api/rest/probes/data-locations/<data_location_name>/api) should be used to validate the REST API readiness prior to using it.
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:
Log in to Semarchy xDM as a user with one of the Application Design, Application Management and Platform Administration platform privileges.
Click the REST API link on the Welcome page.
The documentation exposes the endpoint description and provides request and response samples.
Authentication & Security
This section describes the authentication mechanisms for the REST API and provides simple recommendations to secure the use of this API.
Authentication & Privileges
Applications accessing Semarchy xDM using the REST API must be authenticated.
The REST API supports two authentication methods:
Basic authentication, where you provide an
AuthorizationHTTP header containing
username:passwordencoded 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-KeyHTTP header containing an API key created in Semarchy Configuration. With this authentication method, REST API calls use the identity (Default User Name) and roles defined for the API Key.
Operations in the REST API need privileges similar to those required to perform the same operations via a user interface:
With Basic Authentication, the authenticated user must have roles with sufficient platform and data-level privileges. He must also have a role with a model privilege grant with the Grant access to the Integration API option selected to interact with data in a given model.
With API Key Authentication, the key must be defined with roles that have sufficient platform and data-level privileges. It must also have a role with a model privilege grant with the Grant access to the Integration API option selected to interact with data in a given model.
|See Manage Roles, API keys, and Secure the Data Hub for more information about secured access with the REST API.|
The following simple recommendations will help you secure your code and data when using the REST API.
Both API key and Basic authentication send credentials in plain text in HTTP headers to authenticate: They can be stolen by sniffing the network, unless you use HTTPS.
We highly recommend using the REST API on the secured HTTPS protocol and not on plain HTTP, to keep both the credentials and data transferred secured.
Secure credentials in your code
Choose the right authentication method
API Keys authentication is good for technical or application user authentication. You should generally use API Keys in such case rather than using basic authentication. You can easily manage keys in the platform configuration instead maintaining technical users in your authentication system.
Use the API
Unless specified otherwise, all Semarchy xDM API responses are in the JSON format.
Certain API calls require you to send data in a particular format as part of the API call. By default, all API calls expect a request body in JSON format
Every API call that requires data to be sent by POST or PUT has a different data structure that it expects in the payload. Refer to the documentation for the specific call you are making to see the exact payload formats to complete your request.
The API endpoints report in the response payload possible errors with an appropriate HTTP code. Refer to the documentation for each endpoint for the possible responses.
When calling an endpoint, note that:
Invalid query parameters are ignored and do not raise errors.
Invalid payload content or unexpected properties in the payload raise errors with suggested fixes.