Manage Semarchy xDI Production Analytics with the REST API

Semarchy xDI Production Analytics exposes REST endpoints to perform programmatic management operations on the application.

Overview

The REST API endpoints allow you to manage and operate Delivery Projects. You can import sources, build and deploy deliveries to environments.

Semarchy xDI Production Analytics generates automatically a Swagger descriptor describing all available operations, and is shipped with Swagger-UI which can be used to play with the APIs easily.

REST API URLs

The complete list of available operations and parameters is exposed through a Swagger descriptor file, and an embedded Swagger-UI component allowing to visualize and play with the APIs.

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/swagger.yaml

REST APIs Swagger2 descriptor file. For example:
http://localhost:8080/semarchy-xdi-analytics/services/swagger.yaml

<application_url>/swagger-ui/api/2

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

Authentication

The Basic Authentication is required to use the REST API with a user with the analyticsRepositoryAdmin role. See the installation process for more information about user configuration.

Return Codes

If an issue arises in a REST API call, the Analytics returns a specific error code and message in the JSON response in addition to the HTTP status code.

The functional error may appear for instance when trying to perform operations on objects which do not exist, when trying to deploy deliveries on unavailable runtimes, etc.

The codes and messages are listed below.

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 Semarchy xDI Production 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 Semarchy xDI Production 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.