API docs by Redocly

ODM Platform's DevOps API Reference (v1.0.0)

Download OpenAPI specification:Download

ODM Platform Team: odm.info@quantyca.it License: Apache 2.0

This page describe tha API exposed by ODM Platform's DevOps Service

Open Data Mesh Platform's DevOps API Documentation

Overview

The DevOps Module of the Open Data Mesh platform manages the data product's lifecycle. Specifically, it handles the necessary activities to execute transitions between different stages within the lifecycle. The possible stages and the activities to be performed are described in the 'lifecycle' block of the data product descriptor. To perform a stage transition, it's required to create a new activity, specifying the version of the data product on which it should be executed and the target stage. The DevOps Module then reads the definition of the data product version from the Registry Module, verifies that the target stage exists among those defined in the lifecycle block, and finally creates a plan of tasks to be executed to bring the data product to the desired stage. The activity and its associated tasks are created with a default state of PLANNED. When the activity is initiated, the DevOps Module reads the next task to be executed in the execution plan and submits it to the execution service adapter specified in the data product descriptor, passing the template and configurations as input. When the adapter completes the task execution, it notifies the DevOps Module of the completion and the status, which then proceeds with executing the next task if available, or terminates the activity.

Content Types

The Schema Registry REST server uses content types for both requests and responses to indicate the serialization format of the data as well as the version of the API being used. Currently, the only serialization format supported is JSON and the only version of the API is v1. However, to remain compatible with future versions, you should specify preferred content types in requests and check the content types of responses. The preferred format for content types is application/vnd.odmp.v1+json, where v1 is the API version and json is the serialization format. However, other less specific content types are permitted, including application/vnd.odmp+json to indicate no specific API version should be used (the most recent stable version will be used), application/json, and application/octet-stream. The latter two are only supported for compatibility and ease of use. Your requests should specify the most specific format and version information possible via the HTTP Accept header:

Accept: application/vnd.odmp.v1+json

The server does not supports at the moment content negotiation.

Errors

All API endpoints use a standard error message format for any requests that return an HTTP status indicating an error (any 400 or 500 statuses). For example, a request entity that omits a required field may generate the following response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.schemaregistry.v1+json
{
"status": 404,
"code": 40401,
"description": "Activity not found"
"message": "Activity with id equals to [5] does not exist"
"path": "/api/v1/pp/devops/activities/5"
}

Although it is good practice to check the status code, you may safely parse the response of any non-DELETE API calls and check for the presence of a code field to detect errors. For each endpoints all possible error codes, grouped by http response status, are listed and described with the exception of the following ones that are always possible:

  1. 40000 (Request body is not readable): this error is returned when
  2. 41501 (Request media type not supported): : this error is returned when
  3. 40601 (Request accepted media types not supported): : this error is returned when

Task

Endpoints associated to tasks collection

Get the specified task's status

Get the status of task identified by the input id

path Parameters
id
required
integer <int64>

Identifier of the task

Responses

Response samples

Content type
application/json
{
  • "status": "PLANNED"
}

Stop the specified task

Stop the task identified by the input id if it has not been stoped yet

path Parameters
id
required
integer <int64>

Identifier of the task

query Parameters
action
required
string

Add action parameter to the request to specify which action to perform to change the task's status. STOP is the only possible action executable on tasks

Request Body schema:
required

A TaskResult object

status
string
Enum: "PROCESSED" "FAILED"

Status of the Task

object

Optional JSON results of the Task execution returned from the executor

errors
string

Optional textual set of errors of the Task execution returned from the executor

Responses

Request samples

Content type
Example

Example for a succeeded task

"{\n \"status\": \"PROCESSED\",\n \"results\": {\n \"message\": \"Task executed successfully\"\n \"param\": \"param_value\"\n }\n}"

Response samples

Content type
application/json
{
  • "status": "PLANNED"
}

Get all tasks

Get all tasks

query Parameters
activityId
integer <int64>

Add activityId parameter to the request to get only tasks associated to a specific activity

executor
string

Add executor parameter to the request to get only tasks associated to a specific executor service

status
string
Enum: "PLANNED" "ABORTED" "PROCESSING" "PROCESSED" "FAILED"

Add status parameter to the request to get only tasks in a specific state

Responses

Response samples

Content type
[
  • {
    }
]

Get the specified task

Get the task identified by the input id

path Parameters
id
required
integer <int64>

Identifier of the task

Responses

Response samples

Content type
{
  • "id": 0,
  • "activityId": "string",
  • "executorRef": "azure-devops",
  • "template": "string",
  • "configurations": "string",
  • "status": "PLANNED",
  • "results": {
    },
  • "errors": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "finishedAt": "2019-08-24T14:15:22Z"
}

Activities

Endpoints associated to activities collection

Get all activities

Get all the created activities

query Parameters
dataProductId
string

Add dataProductId parameter to the request to get only activities associated to a specific data product

dataProductVersion
string

Add dataProductVersion parameter to the request to get only activities associated to a specific data product version

stage
string

Add stage parameter to the request to get only activities of the specific stage

status
string
Enum: "PLANNED" "PROCESSING" "PROCESSED" "FAILED"

Add status parameter to the request to get only activities in the specific state

Responses

Response samples

Content type
[
  • {
    }
]

Create a new activity

Create new activity of the given type and all its associated tasks on the specified data product. By default the activity and all it's tasks after creation are in PLANNED state. To start the activity after creation pass also the parameter startAfterCreation set to true or call the proper endpoint (see below)

query Parameters
startAfterCreation
boolean

Pass true to start the activity after creation

Request Body schema:
required

An activity object

id
integer <int64>

Auto generated Activity ID

dataProductId
required
string

ID of the Data Product subject of the Activity

dataProductVersion
required
string

Version of the Data Product subject of the Activity

stage
required
string

Goal stage of the Activity

status
string
Enum: "PLANNED" "PROCESSING" "PROCESSED" "FAILED"

Auto updated Activity status

object

Auto updated Activity execution results

errors
string

Auto updated Activity execution errors

createdAt
string <date-time>

Activity creation timestamp

startedAt
string <date-time>

Timestamp of the Activity execution start

finishedAt
string <date-time>

Timestamp of the Activity execution end

Responses

Request samples

Content type

description of example one

{
  • "dataProductId": "c18b07ba-bb01-3d55-a5bf-feb517a8d901",
  • "dataProductVersion": "1.0.0",
  • "stage": "prod"
}

Response samples

Content type
application/json

one

{
  • "dataProductId": "c18b07ba-bb01-3d55-a5bf-feb517a8d901",
  • "dataProductVersion": "1.0.0",
  • "stage": "prod"
}

Get the specified activity's status

Get the status of activity identified by the input id

path Parameters
id
required
integer <int64>

Identifier of the activity

Responses

Response samples

Content type
application/json
{
  • "status": "PLANNED"
}

Start the specified activity

Start the activity identified by the input id if it has not been started yet

path Parameters
id
required
integer <int64>

Identifier of the activity

query Parameters
action
required
string

Add action parameter to the request to specify which action to perform to change the activity's status. START is the only possible action executable on activities

Responses

Response samples

Content type
application/json
{
  • "status": "PLANNED"
}

Get the specified activity

Get the activity identified by the input id

path Parameters
id
required
integer <int64>

Identifier of the activity

Responses

Response samples

Content type
{
  • "id": 0,
  • "dataProductId": "string",
  • "dataProductVersion": "string",
  • "stage": "string",
  • "status": "PLANNED",
  • "results": {
    },
  • "errors": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "finishedAt": "2019-08-24T14:15:22Z"
}

Lifecycles

Endpoints associated to data product's lifecycles collection

Get all lifecycles

Get all lifecycles

Responses

Response samples

Content type
[
  • {
    }
]

Get all lifecycles for the specified data product

Get all the lifecycles associated to the input dataProductId

path Parameters
dataProductId
required
string

Identifier of the data product

Responses

Response samples

Content type
[
  • {
    }
]

Get the lifecycles for the specified tuple <data product - version number>

Get the lifecycles identified by the input dataProductId and versionNumber

path Parameters
dataProductId
required
string

Identifier of the data product

versionNumber
required
string

Version number of the data product

Responses

Response samples

Content type
[
  • {
    }
]

Get the current lifecycle for the specified tuple <data product - version number>

Get the current lifecycle identified by the input dataProductId and versionNumber

path Parameters
dataProductId
required
string

Identifier of the data product

versionNumber
required
string

Version number of the data product

Responses

Response samples

Content type
{
  • "id": 0,
  • "dataProductId": "string",
  • "dataProductVersion": "string",
  • "stage": "string",
  • "results": {
    },
  • "startedAt": "2019-08-24T14:15:22Z",
  • "finishedAt": "2019-08-24T14:15:22Z"
}