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 the base URL. Additional parameters may also be included in the URL.

URL parameter names are case-sensitive. Make sure to use the exact case as described in this documentation. For example $baseExprs is a valid parameter, while $baseexprs or $BASEXPRS are invalid and will be ignored.

REST API readiness

The REST API exposes probe endpoints (/api/rest/probes/) designed to monitor the platform, REST API, and application 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 confirm the readiness of the REST API prior to using it.

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 either Application Design, Application Management, or Platform Administration platform privileges.

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

The documentation includes endpoint descriptions and provides request and response samples.

Authentication and security

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

Authentication and privileges

Applications accessing Semarchy xDM through the REST API require authentication. The REST API supports two authentication methods:

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

  • API key authentication involves providing an API-Key HTTP header containing an API key created in Semarchy Configuration. This method enables REST API calls to use the identity (default username) and roles defined for the API key.

Operations within the REST API necessitate privileges similar to those required for performing equivalent operations through a user interface:

  • With basic authentication, the authenticated user must possess roles with adequate platform and data-level privileges. They must also be assigned a role with a model privilege grant with the Grant access to the Integration API option selected, to interact with data within a given model.

  • With API key authentication, the key must be configured with roles possessing 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 within a given model.

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

Security recommendations

The following recommendations for enhancing code and data security when utilizing the REST API:

  • Use HTTPS: both API key and basic authentication transmit credentials in plaintext via HTTP headers to authenticate. These are susceptible to interception via network sniffing, unless encrypted with HTTPS.
    We highly recommend using the REST API over the secured HTTPS protocol rather than plain HTTP to ensure the security of both credentials and transferred data.

  • Secure credentials in your code: client-side code containing credentials should remain private and inaccessible to the public. For instance, avoid embedding API keys in JavaScript visible to all users in their browser.

  • Choose the appropriate authentication method: API key authentication is suitable for technical or application user authentication. It is generally advisable to use API keys in these scenarios rather than basic authentication. Managing keys within the platform configuration is preferable to maintaining technical users in your authentication system.

Use the API

Data formats

Unless specified otherwise, all Semarchy xDM API responses are provided in JSON format.

Certain API calls require data to be transmitted in a particular format as part of the call. By default, all API calls expect a JSON-formatted request body.

Each API call mandating data submission via POST or PUT expects a unique data structure within the payload. For the precise payload formats to complete your request, see the documentation corresponding to the specific call you are executing.

Errors

When interacting with API endpoints, possible errors are communicated in the response payload along with the appropriate HTTP code. For the possible responses associated with each endpoint, see the REST API documentation.

When calling an endpoint, keep in mind the following:

  • Invalid query parameters are ignored and do not trigger errors.

  • Invalid payload content or unexpected properties in the payload raise errors with suggested fixes.