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 automatically generates 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

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>/services/openapi3.json`	REST APIs OpenAPI v3 descriptor. 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 Swagger2 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/swagger.yaml

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

<application_url>/services/openapi3.json

REST APIs OpenAPI v3 descriptor. 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 Swagger2 descriptor. For example:
http://localhost:8080/semarchy-xdi-analytics/swagger-ui/api/2/index.html

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.