REST API integration

The REST API provides programmatic access to consume, certify, and publish data in a data hub.

Overview

The REST API is available at the following base URL (referred to as [base_url]):

http://<host>:<port>/semarchy/api/rest/

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 $baseExprs is a valid parameter, but $baseexprs or $BASEXPRS are invalid and will be ignored.

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:

  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.

The documentation exposes the endpoint description and provides request and response samples.

Authentication and security

This section describes the authentication mechanisms for the REST API and provides simple recommendations to secure the use of this API.

Authentication and 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 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 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.

Security recommendation

The following simple recommendations will help you secure your code and data when using the REST API.

  • Use HTTPS
    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
    The client code needs to have those credentials and this code should not be publicly visible with the credentials. For instance, it is a bad practice to have the API Key embedded in the javascript code available to all users in their browser.

  • 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

Data formats

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.

Errors

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.