xDI Runtime REST API for delivery operations

Overview

xDI Runtime exposes a REST API to retrieve information about delivery repositories, retrieve delivery information, and manage deliveries.

This API complements other ways of managing deliveries such as the Runtime command line.

Base URL

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

/api/{version}/

Add it to the address of your runtime to form the base address for the API:

{runtime_protocol}{hostname}:{port}/api/{version}/

With a default runtime installation, using API version 1, the base address may look like this example:

http://localhost:42200/api/1/

Authorization

By default, HTTP basic authentication is required for requests to this API.

curl \
  --header 'Authorization: Basic YWRtaW46YWRtaW4tcGFzc3dvcmQ='

The API endpoints also require runtime user roles depending on the verb you use. The View role grants permission to make GET requests, and the Admin role grants permission to make any request.

Version

The current API version is 1.

HTTP status codes

The Runtime API uses the following standard HTTP response codes:

Status code Description

200 OK

The request is successful.

401 Unauthorized

Authentication credentials are invalid.

404 Not Found

The requested resource is not found.

409 Conflict

The request conflicts with an existing resource.

500 Internal Server Error

The server encounters an internal error when trying to fulfill the request.

Errors

When the Runtime API returns an HTTP code other than 200, it returns a JSON response with the following fields:

Error Description

timestamp

The date and time of the error.

status

The HTTP error code.

error

The HTTP error message.

message

An API error message.

path

The URL path of the request.
Example 1. Example error
{
    "timestamp": "2024-07-04T08:14:11.620+00:00",
    "status": 404,
    "error": "Not Found",
    "message": "[ERROR_ID : 1b4c1dfd-dece-47c7-98ea-97ab4f72b6ef]. Contact your administrator for more informations",
    "path": "/api/1/deliveries/deliveryNotfound"
}

Delivery repositories

The delivery repositories resource is used to get information about delivery repositories known to a runtime. You can retrieve a list of repositories, or get detailed information about a single repository.

Use the following endpoints to interact with deliveries.

Table 1. Endpoints
Endpoint name Description

GET /api/1/delivery-repositories

Retrieves the list of delivery repositories known to a runtime.

GET /api/1/delivery-repositories/{repository}

Retrieves detailed information about a delivery repository.

Get a list of repositories

Retrieves a list of all delivery repositories known to a runtime.

GET /api/1/delivery-repositories

Authorization

This endpoint requires the requestor to have View or Admin permissions for the runtime.

Request example

curl --request GET \
  --url http://localhost:42200/api/1/delivery-repositories \
  --header 'Authorization: Basic YWRtaW46YWRtaW4tcGFzc3dvcmQ='

Response example

{
  "description": "The list of repositories",
  "repositories": [
    {
      "synchronizationPollingInterval": 10000,
      "name": "default",
      "scanMode": "poll",
      "type": "File",
      "default": true,
      "webservice": false
    },
    {
      "synchronizationPollingInterval": 10000,
      "name": "webservices",
      "scanMode": "poll",
      "type": "File",
      "default": true,
      "webservice": true
    },
    {
      "synchronizationPollingInterval": 10000,
      "name": "azure_repository",
      "scanMode": "poll",
      "type": "Azure Blob Storage",
      "default": false,
      "webservice": false
    }
  ]
}

Get information about a repository

Retrieves detailed information about a single delivery repository known to a runtime.

GET /api/1/delivery-repositories/{repository}

Authorization

This endpoint requires the requestor to have View or Admin permissions for the runtime.

Path parameters

Path parameter Type Required? Description

repository

string

Yes

The name of a delivery repository to get information about.

Request example

curl --request GET \
  --url http://localhost:42200/api/1/delivery-repositories/webservices \
  --header 'Authorization: Basic YWRtaW46YWRtaW4tcGFzc3dvcmQ='

Response example

{
  "description": "The list of repositories",
  "repositories": [
    {
      "synchronizationPollingInterval": 10000,
      "name": "webservices",
      "scanMode": "poll",
      "type": "File",
      "default": true,
      "webservice": true
    }
  ]
}

Deliveries

The Delivery resource is used to interact with a runtime’s deliveries. You can add, remove, or update deliveries, as well as retrieve information about them. Use parameters to control which delivery repository to use for operations, and to specify the path within the remote repository.

Use the following endpoints to interact with deliveries.

Table 2. Endpoints
Endpoint name Description

GET /api/1/deliveries

Retrieves the list of deliveries in a repository.

GET /api/1/deliveries/{delivery}

Retrieves detailed information about a delivery.

POST /api/1/deliveries/{delivery}

Sends a delivery to a repository.

PUT /api/1/deliveries/{delivery}

Sends and updates a delivery in a repository.

DELETE /api/1/deliveries/{delivery}

Deletes and removes a delivery from a repository.

Get a list of deliveries

Retrieves a list of all deliveries in a delivery repository.

GET /api/1/deliveries

Authorization

This endpoint requires the requestor to have View or Admin permissions for the runtime.

Query parameters

Query parameter Type Required? Description

repository

string

No

The name of a delivery repository. The name must match an entry in the runtime’s engineParameters.xml configuration file. When this parameter is empty, the default repository is used.

Request example

curl --request GET \
  --url http://localhost:42200/api/1/deliveries \
  --header 'Authorization: Basic YWRtaW46YWRtaW4tcGFzc3dvcmQ='

Response example

{
  "description": "The list of deliveries",
  "repository": "default",
  "deliveries": [
    {
      "identifier": "93150e89-a9de-4af5-8b17-6e0c5f6eb18b",
      "name": "getJsonCustomerDetails",
      "buildUser": "AlbertDURAND",
      "buildDate": "2022-03-24T11:45:10.712+00:00",
      "configurationCode": "Default"
    },
    {
      "identifier": "ae7ddcd3-9530-47f5-a863-ff1974bcbed7",
      "name": "getCityLocation",
      "buildUser": "JohnSMITH",
      "buildDate": "2022-10-17T16:48:44.174+00:00",
      "configurationCode": "Default"
    }
  ]
}

Get information about a delivery

Retrieves detailed information about a single delivery in a delivery repository.

GET /api/1/deliveries/{delivery}

Authorization

This endpoint requires the requestor to have View or Admin permissions for the runtime.

Path parameters

Path parameter Type Required? Description

delivery

string

Yes

The filename of a delivery to get information about. You can use the filename with or without the .deliv file extension.

Query parameters

Query parameter Type Required? Description

repository

string

No

The name of a delivery repository. The name must match an entry in the runtime’s engineParameters.xml configuration file. When this parameter is empty, the default repository is used.

path

string

No

Remote path of the delivery, relative to the top level of the repository.

Request example

curl --request GET \
  --url 'http://localhost:42200/api/1/deliveries/getMoreInfo?repository=webservices&path=subfolder' \
  --header 'Authorization: Basic YWRtaW46YWRtaW4tcGFzc3dvcmQ='

Response example

{
  "description": "The list of deliveries",
  "repository": "webservices",
  "deliveries": [
    {
      "identifier": "ae7ddcd3-9530-47f5-a863-ff1974bcbed7",
      "name": "getMoreInfo",
      "buildUser": "JaneDOE",
      "buildDate": "2022-10-17T16:48:44.174+00:00",
      "configurationCode": "Default"
    }
  ]
}

Push a delivery to a repository

Sends a delivery to a delivery repository. When using this endpoint, you must send the delivery file contents as text data, and add the header Content-Type: application/octet-stream to your request.

POST /api/1/deliveries/{delivery}
This action is not supported for xDI Analytics repositories.

Authorization

This endpoint requires the requestor to have Admin permissions for the runtime.

Path parameters

Path parameter Type Required? Description

delivery

string

Yes

The filename given to the delivery when it is saved in the repository. You can use the filename with or without the .deliv file extension.

Query parameters

Query parameter Type Required? Description

repository

string

No

The name of a delivery repository. The name must match an entry in the runtime’s engineParameters.xml configuration file. When this parameter is empty, the default repository is used.

path

string

No

Remote path of the delivery, relative to the top level of the repository.

overwrite

boolean

No

Whether or not to overwrite deliveries when sending one with a similar name.

false:: Do not overwrite deliveries, and throw an error if a delivery by the same name exists. This value is the default. true:: Overwrite existing deliveries.

Request example

curl --request POST \
  --url 'http://localhost:42200/api/1/deliveries/aNewDeliveryName?repository=webservices&overwrite=false&path=subfolder' \
  --header 'Authorization: Basic YWRtaW46YWRtaW4tcGFzc3dvcmQ=' \
  --header 'Content-Type: application/octet-stream' \
  --data '<?xml version="1.0" encoding="UTF-8"?><deliv:delivery xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:mdj="java:com.semarchy.xdi.designer.generation.xsl.global.Functions" xmlns:deliv="http://www.stambia.com/deliv" checksumVersion="1" checksum="18C45E8ECDE78E1FA63F30723246B52E7FE75758" allowedScriptErrors="false" allowedVariableErrors="false" buildDate="2024-02-28T10:52:09.539+01:00" buildUser="John Smith" configurationCode="Default" exportDate="2024-02-28T10:52:09.539+01:00" exportUser="John Smith" id="0cf658d8-b35e-407c-be10-190e86d5463b" processId="d94f7921-f6f5-4d59-83a9-b272c7bb69ef"></deliv:delivery>'

Response example

{
  "name": "aNewDeliveryName",
  "version": null,
  "id": "ae7ddcd3-9530-47f5-a863-ff1974bcbed7",
  "lastModified": 1720704946664
}

Update a delivery in a repository

Sends a delivery to update an existing one in a delivery repository. When using this endpoint, you must send the delivery file contents as text data, and add the header Content-Type: application/octet-stream to your request.

PUT /api/1/deliveries/{delivery}
This action is not supported for xDI Analytics repositories.

Authorization

This endpoint requires the requestor to have Admin permissions for the runtime.

Path parameters

Path parameter Type Required? Description

delivery

string

Yes

The filename of the delivery as it exists in the repository. You can use the filename with or without the .deliv file extension.

Query parameters

Query parameter Type Required? Description

repository

string

No

The name of a delivery repository. The name must match an entry in the runtime’s engineParameters.xml configuration file. When this parameter is empty, the default repository is used.

path

string

No

Remote path of the delivery, relative to the top level of the repository.

Request example

curl --request PUT \
  --url 'http://localhost:42200/api/1/deliveries/aNewDeliveryName?repository=webservices&path=subfolder' \
  --header 'Authorization: Basic YWRtaW46YWRtaW4tcGFzc3dvcmQ=' \
  --header 'Content-Type: application/octet-stream' \
  --data '<?xml version="1.0" encoding="UTF-8"?><deliv:delivery xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:mdj="java:com.semarchy.xdi.designer.generation.xsl.global.Functions" xmlns:deliv="http://www.stambia.com/deliv" checksumVersion="1" checksum="18C45E8ECDE78E1FA63F30723246B52E7FE75758" allowedScriptErrors="false" allowedVariableErrors="false" buildDate="2024-02-28T10:52:09.539+01:00" buildUser="John Smith" configurationCode="Default" exportDate="2024-02-28T10:52:09.539+01:00" exportUser="John Smith" id="0cf658d8-b35e-407c-be10-190e86d5463b" processId="d94f7921-f6f5-4d59-83a9-b272c7bb69ef"></deliv:delivery>'

Response example

{
  "name": "aNewDeliveryName",
  "version": null,
  "id": "0cf658d8-b35e-407c-be10-190e86d5463b",
  "lastModified": 1720705093388
}

Delete a delivery in a repository

Deletes an existing delivery in a delivery repository. If this requests successfully deletes a delivery, it returns an HTTP 200 OK response with no body.

DELETE /api/1/deliveries/{delivery}
This action is not supported for xDI Analytics repositories.

Authorization

This endpoint requires the requestor to have Admin permissions for the runtime.

Path parameters

Path parameter Type Required? Description

delivery

string

Yes

The filename of the delivery as it exists in the repository. You can use the filename with or without the .deliv file extension.

Query parameters

Query parameter Type Required? Description

repository

string

No

The name of a delivery repository. The name must match an entry in the runtime’s engineParameters.xml configuration file. When this parameter is empty, the default repository is used.

path

string

No

Remote path of the delivery, relative to the top level of the repository.

Request example

curl --request DELETE \
  --url 'http://localhost:42200/api/1/deliveries/aNewDeliveryName?repository=webservices&path=subfolder' \
  --header 'Authorization: Basic YWRtaW46YWRtaW4tcGFzc3dvcmQ='