Manage Semarchy xDI Analytics with the REST API

Overview

xDI Analytics exposes a REST API to manage and operate delivery projects. You can use the REST API to import sources, build deliveries, and deploy deliveries to environments.

Base URL

The following is the base URL path for the Analytics API:

services/api/{version}/

Add it to the Analytics to form the base address for the API:

{protocol}{hostname}:{port}services/api/{version}/

With a default Analytics installation, the base address may look like this example:

http://localhost:8080/semarchy-xdi-analytics/services/api/2

Authorization

To use the Analytics REST API, you must use HTTP basic authentication with an Analytics user that has the analyticsRepositoryAdmin role.

For information about this role, see the Analytics installation documentation.

Version

The current API version is 2.

Error codes

If an issue arises in a REST API call, Analytics returns a JSON response containing an error code and message, as well as an HTTP status code. The codes and messages are listed in the following table.

Table 1. REST API error codes and messages
Error Code	HTTP Status Code	Message	Description	Resolution
STA-REPO-001	404	No Repository found	The application repository cannot be found. This error should not happen unless the Analytics storage was deleted in xDI Analytics database.	The storage may have been unexpectedly modified. Check the storage in the database schema.
STA-REPO-003	404	No Version found	The target package manager version does not exist.	Check that a package manager version with that name exists.
STA-REPO-004	404	No Environment found	The target environment does not exist.	Check that an environment with that name exists, and that it is associated with the target delivery project.
STA-REPO-006	404	No Build found	This error happens when trying to deploy deliveries using a deployment that contains no build.	Use the build operation on the same environment and version, and then re-try to deploy.
STA-REPO-007	200	An error occurred while deploying	This generic error appears when an issue occurred while deploying to the given environment.	More details are provided in the response payload to investigate and fix the issue.
STA-REPO-008	200	Error deploying delivery	This error appears when an issue occurred while deploying deliveries to the given environment.	More details are provided in the response payload to investigate and fix the issue.
STA-REPO-009	424	Missing Metadata	This error appears when performing a build on an environment into which required metadata attributes values are unset.	Connect to xDI Analytics and fix the missing values in the corresponding Delivery Project, Package Manager Version, Environment. Metadata attributes definition is possible in the user interface and not via the API.
STA-REPO-010	404	No Package Manager found	The target Package Manager does not exist.	Check that a package manager with that name exists.
STA-REPO-011	409	A Package Manager already exists with the same name	This error happens when creating a Package Manager that already exists.
STA-REPO-012	404	No Delivery Project found	The target Delivery Project does not exist.	Check that a delivery project with that name exists.
STA-REPO-016	409	A Version already exists with the same name	This error happens when creating a package manager version that already exists.
STA-REPO-017	422	Invalid Version Name: name can only contain characters, numbers, points, and underscores	This error happens when trying to create a package manager version with an invalid name.	Change the name to use only valid characters.
STA-REPO-018	422	Invalid Package Manager Name: name can only contain characters, numbers, underscores, and spaces	This error happens when trying to create a package manager with an invalid name.	Change the name to use only valid characters.
STA-AUTH-ERROR	403	Unauthorized	The user does not have permission to use the API endpoint.	The permission required to use the API is analyticsRepositoryAdmin. Refer to User configuration for more information about users and permissions.

Example 1. Example error

{
  "message": "No Environment found",
  "errors": [
    {
      "code": "STA-REPO-004",
      "message": "No Environment found"
    }
  ],
  "status": "error"
}

API definition

Consult the complete list of available operations and parameters through descriptor files and an embedded Swagger-UI component.

URL Description

URL	Description
`<application_url>/services/api/2`	Base URL for the REST endpoints. For example: http://localhost:8080/semarchy-xdi-analytics/services/api/2
`<application_url>/services/openapi3.yaml`	REST API OpenAPI v3 descriptor file, in YAML format. For example: http://localhost:8080/semarchy-xdi-analytics/services/openapi3.yaml
`<application_url>/services/openapi3.json`	REST API OpenAPI v3 descriptor, in JSON format. For example: http://localhost:8080/semarchy-xdi-analytics/services/openapi3.json
`<application_url>/swagger-ui/api/2`	Swagger-UI tool to experiment with the API using the OpenAPI v3 descriptor. For example: http://localhost:8080/semarchy-xdi-analytics/swagger-ui/api/2/index.html

<application_url>/services/api/2

Base URL for the REST endpoints. For example:
http://localhost:8080/semarchy-xdi-analytics/services/api/2

<application_url>/services/openapi3.yaml

REST API OpenAPI v3 descriptor file, in YAML format. For example:
http://localhost:8080/semarchy-xdi-analytics/services/openapi3.yaml

<application_url>/services/openapi3.json

REST API OpenAPI v3 descriptor, in JSON format. For example:
http://localhost:8080/semarchy-xdi-analytics/services/openapi3.json

<application_url>/swagger-ui/api/2

Swagger-UI tool to experiment with the API using the OpenAPI v3 descriptor. For example:
http://localhost:8080/semarchy-xdi-analytics/swagger-ui/api/2/index.html

Environment

The Environment resource is used to get information about configurations and runtimes used when building and deploying deliveries with Package Managers.

Use the following endpoints to interact with the environment resource.

Table 2. Endpoints
Endpoint name	Description
GET /api/2/environment/{env_name}/deliveries	Return version delivery list

Package

The Package resource is used to work with packages and their environments and versions.

Use the following endpoints to interact with projects and their packages.

Table 3. Endpoints
Endpoint name	Description
POST /api/2/project/{project_name}/package/{package_name}	Create Package
POST /api/2/project/{project_name}/package/{package_name}/environment/{env_name}/version/{version_name}/build	Build Version
POST /api/2/project/{project_name}/package/{package_name}/environment/{env_name}/version/{version_name}/deploy	Deploy Version
POST /api/2/project/{project_name}/package/{package_name}/environment/{env_name}/version/{version_name}/working	Set version to working by name
GET /api/2/project/{project_name}/package/{package_name}/environment/{env_name}/working_version/name	Return Working Version name
PATCH /api/2/project/{project_name}/package/{package_name}/version/{version_name}	Import pck to a Version
POST /api/2/project/{project_name}/package/{package_name}/version/{version_name}	Create a new Version
PUT /api/2/project/{project_name}/package/{package_name}/version/{version_name}	Remove all pck from Version and import a new one
POST /api/2/project/{project_name}/package/{package_name}/version/{version_name}/duplicate/{duplicate_version_name}	Duplicate version

Notes

The Import pck to a Version endpoint requires specific Body parameters to send a file:

Body type form-data
A fileUpload key of type File

Example in cURL:

curl --location --request PATCH 'http://localhost:8080/semarchy-xdi-analytics/services/api/2/project/myproject/package/mypackage/version/myversion' \
--header 'Authorization: Basic xxxxxxxxxx=' \
--form 'fileUpload=@"/Users/xdi/packages/mypackage.pck"'