Skip to main content

Tech Adapter API

note

Read this page in wide view mode from here

API docs by Redocly

Tech Adapter API (2.6.3)

A Tech Adapter is responsible for integrating a specific technology into Witboost.

By implementing this Open API contract, the Tech Adapter microservice can be used by the Witboost platform to deploy, undeploy, and eventually manage the access control list of the technology components.

Once you deploy the Tech Adapter microservice, you can register it in the Witboost platform using the Builder API. The API is also used to validate the provisioning descriptors and to execute reverse provisioning operations.

TechAdapter

Validate a provisioning request (async)

Start a validation process with the input descriptor and return a token that can be used to check the status of the validation process.

You want to implement this endpoint to assess that the provided resource descriptor conforms to the expected structure and has all the necessary information to be deployed on the infrastructure.

Implementing the asynchronous endpoint rather than the synchronous one is highly recommended even if the validation operation is not time-consuming.

Request Body schema: application/json
required

Details of a provisioning request to be validated

descriptorKind
required
string (DescriptorKind)
Enum: "DATAPRODUCT_DESCRIPTOR" "COMPONENT_DESCRIPTOR" "DATAPRODUCT_DESCRIPTOR_WITH_RESULTS"

It can change according to the descriptor kind:

  • DATAPRODUCT_DESCRIPTOR: Descriptor of a system, comprehensive of its components.
  • COMPONENT_DESCRIPTOR: Descriptor of a component. Includes both the system descriptor (dataProduct object field) and the id of the component that is being provisioned (componentIdToProvision string field).
  • DATAPRODUCT_DESCRIPTOR_WITH_RESULTS: Not being used in the scope of a tech adapter.
descriptor
required
string

Resource descriptor in YAML format. Its structure changes according to descriptorKind.

If a component is dependent on another one, the COMPONENT_DESCRIPTOR descriptor will be enriched with the Provisioning Info of the dependency component. This does NOT apply to validation endpoints

latestEnrichedDescriptor
string

Filled only in case of provision/unprovision requests.

System descriptor enriched with provisioning info generated during the latest (successful or failed) provisioning/unprovisioning operation for each component.

If available, provisioning information is reported in the info fields at both the system and component levels. The base schema for the info object is the same as Info, but additional fields may be included, such as the latestProvisioningOperation object. This object contains information about the most recent provisioning operation performed on the component, including the operation type (e.g. Deploy, Undeploy) in the operation field, as well as the status of the operation (e.g. NotStarted, Failed, Successful) in the status field.

Please note that the information contained in a info object represents the most recent data provided by a tech adapter for the corresponding component. However, this information may not have been provided during the last system provisioning operation. For example, if the provisioning operation fails and the component's tech adapter is not called, the information doesn't change. Only the latestProvisioningOperation object always refers to the most recent provisioning operation on the system.

removeData
required
boolean
Default: false

If true, when a component is undeployed, its underlying data will also be deleted

Responses

Request samples

Content type
application/json
Example
{
  • "descriptorKind": "DATAPRODUCT_DESCRIPTOR",
  • "descriptor": "dataProduct:\n id: urn:dmb:dp:finance:a-system:0\n components: \n - id: urn:dmb:dp:finance:a-system:0:component:0\n name: S3 storage\n description: A system that does something\n kind: storage\n version: 0.0.1\n - id: urn:dmb:dp:finance:a-system:0:component:1\n name: A system that does something\n description: A system that does something\n kind: outputport\n version: 0.0.1\nremoveData: false",
  • "removeData": false
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "userMessage": "The descriptor field is required",
  • "moreInfo": {
    },
  • "solutions": [
    ]
}

Get status of an async validation task

path Parameters
token
required
string
Example: 3da5d0a2-9f3b-4a11-85a3-b5ddb73da032

Token obtained after a call to the async validate endpoint

Responses

Response samples

Content type
application/json
Example
{
  • "status": "COMPLETED",
  • "info": {
    }
}

Validate a provisioning request (sync)

Synchronously validate a provisioning request and return the validation result.

You want to implement this endpoint to assess that the provided resource descriptor conforms to the expected structure and has all the necessary information to be deployed on the infrastructure.

It is highly recommended to implement the asynchronous validation endpoint instead of this one.

Request Body schema: application/json
required

Details of a provisioning request to be validated

descriptorKind
required
string (DescriptorKind)
Enum: "DATAPRODUCT_DESCRIPTOR" "COMPONENT_DESCRIPTOR" "DATAPRODUCT_DESCRIPTOR_WITH_RESULTS"

It can change according to the descriptor kind:

  • DATAPRODUCT_DESCRIPTOR: Descriptor of a system, comprehensive of its components.
  • COMPONENT_DESCRIPTOR: Descriptor of a component. Includes both the system descriptor (dataProduct object field) and the id of the component that is being provisioned (componentIdToProvision string field).
  • DATAPRODUCT_DESCRIPTOR_WITH_RESULTS: Not being used in the scope of a tech adapter.
descriptor
required
string

Resource descriptor in YAML format. Its structure changes according to descriptorKind.

If a component is dependent on another one, the COMPONENT_DESCRIPTOR descriptor will be enriched with the Provisioning Info of the dependency component. This does NOT apply to validation endpoints

latestEnrichedDescriptor
string

Filled only in case of provision/unprovision requests.

System descriptor enriched with provisioning info generated during the latest (successful or failed) provisioning/unprovisioning operation for each component.

If available, provisioning information is reported in the info fields at both the system and component levels. The base schema for the info object is the same as Info, but additional fields may be included, such as the latestProvisioningOperation object. This object contains information about the most recent provisioning operation performed on the component, including the operation type (e.g. Deploy, Undeploy) in the operation field, as well as the status of the operation (e.g. NotStarted, Failed, Successful) in the status field.

Please note that the information contained in a info object represents the most recent data provided by a tech adapter for the corresponding component. However, this information may not have been provided during the last system provisioning operation. For example, if the provisioning operation fails and the component's tech adapter is not called, the information doesn't change. Only the latestProvisioningOperation object always refers to the most recent provisioning operation on the system.

removeData
required
boolean
Default: false

If true, when a component is undeployed, its underlying data will also be deleted

Responses

Request samples

Content type
application/json
Example
{
  • "descriptorKind": "DATAPRODUCT_DESCRIPTOR",
  • "descriptor": "dataProduct:\n id: urn:dmb:dp:finance:a-system:0\n components: \n - id: urn:dmb:dp:finance:a-system:0:component:0\n name: S3 storage\n description: A system that does something\n kind: storage\n version: 0.0.1\n - id: urn:dmb:dp:finance:a-system:0:component:1\n name: A system that does something\n description: A system that does something\n kind: outputport\n version: 0.0.1\nremoveData: false",
  • "removeData": false
}

Response samples

Content type
application/json
Example
{
  • "valid": true
}

Provision a resource

Deploy a system or a single component starting from its descriptor.

The descriptor is a YAML file that describes the resource to be deployed. The structure of the descriptor changes according to the descriptorKind field.

Request Body schema: application/json
required
descriptorKind
required
string (DescriptorKind)
Enum: "DATAPRODUCT_DESCRIPTOR" "COMPONENT_DESCRIPTOR" "DATAPRODUCT_DESCRIPTOR_WITH_RESULTS"

It can change according to the descriptor kind:

  • DATAPRODUCT_DESCRIPTOR: Descriptor of a system, comprehensive of its components.
  • COMPONENT_DESCRIPTOR: Descriptor of a component. Includes both the system descriptor (dataProduct object field) and the id of the component that is being provisioned (componentIdToProvision string field).
  • DATAPRODUCT_DESCRIPTOR_WITH_RESULTS: Not being used in the scope of a tech adapter.
descriptor
required
string

Resource descriptor in YAML format. Its structure changes according to descriptorKind.

If a component is dependent on another one, the COMPONENT_DESCRIPTOR descriptor will be enriched with the Provisioning Info of the dependency component. This does NOT apply to validation endpoints

latestEnrichedDescriptor
string

Filled only in case of provision/unprovision requests.

System descriptor enriched with provisioning info generated during the latest (successful or failed) provisioning/unprovisioning operation for each component.

If available, provisioning information is reported in the info fields at both the system and component levels. The base schema for the info object is the same as Info, but additional fields may be included, such as the latestProvisioningOperation object. This object contains information about the most recent provisioning operation performed on the component, including the operation type (e.g. Deploy, Undeploy) in the operation field, as well as the status of the operation (e.g. NotStarted, Failed, Successful) in the status field.

Please note that the information contained in a info object represents the most recent data provided by a tech adapter for the corresponding component. However, this information may not have been provided during the last system provisioning operation. For example, if the provisioning operation fails and the component's tech adapter is not called, the information doesn't change. Only the latestProvisioningOperation object always refers to the most recent provisioning operation on the system.

removeData
required
boolean
Default: false

If true, when a component is undeployed, its underlying data will also be deleted

Responses

Request samples

Content type
application/json
Example
{
  • "descriptorKind": "DATAPRODUCT_DESCRIPTOR",
  • "descriptor": "dataProduct:\n id: urn:dmb:dp:finance:a-system:0\n components: \n - id: urn:dmb:dp:finance:a-system:0:component:0\n name: S3 storage\n description: A system that does something\n kind: storage\n version: 0.0.1\n - id: urn:dmb:dp:finance:a-system:0:component:1\n name: A system that does something\n description: A system that does something\n kind: outputport\n version: 0.0.1\nremoveData: false",
  • "removeData": false
}

Response samples

Content type
application/json
Example
{
  • "status": "COMPLETED",
  • "info": {
    }
}

Unprovision a resource

Undeploy a system or a single component starting from the latest provisioned descriptor.

The descriptor is a YAML file that describes the resource to be deployed. The structure of the descriptor changes according to the descriptorKind field.

Request Body schema: application/json
required
descriptorKind
required
string (DescriptorKind)
Enum: "DATAPRODUCT_DESCRIPTOR" "COMPONENT_DESCRIPTOR" "DATAPRODUCT_DESCRIPTOR_WITH_RESULTS"

It can change according to the descriptor kind:

  • DATAPRODUCT_DESCRIPTOR: Descriptor of a system, comprehensive of its components.
  • COMPONENT_DESCRIPTOR: Descriptor of a component. Includes both the system descriptor (dataProduct object field) and the id of the component that is being provisioned (componentIdToProvision string field).
  • DATAPRODUCT_DESCRIPTOR_WITH_RESULTS: Not being used in the scope of a tech adapter.
descriptor
required
string

Resource descriptor in YAML format. Its structure changes according to descriptorKind.

If a component is dependent on another one, the COMPONENT_DESCRIPTOR descriptor will be enriched with the Provisioning Info of the dependency component. This does NOT apply to validation endpoints

latestEnrichedDescriptor
string

Filled only in case of provision/unprovision requests.

System descriptor enriched with provisioning info generated during the latest (successful or failed) provisioning/unprovisioning operation for each component.

If available, provisioning information is reported in the info fields at both the system and component levels. The base schema for the info object is the same as Info, but additional fields may be included, such as the latestProvisioningOperation object. This object contains information about the most recent provisioning operation performed on the component, including the operation type (e.g. Deploy, Undeploy) in the operation field, as well as the status of the operation (e.g. NotStarted, Failed, Successful) in the status field.

Please note that the information contained in a info object represents the most recent data provided by a tech adapter for the corresponding component. However, this information may not have been provided during the last system provisioning operation. For example, if the provisioning operation fails and the component's tech adapter is not called, the information doesn't change. Only the latestProvisioningOperation object always refers to the most recent provisioning operation on the system.

removeData
required
boolean
Default: false

If true, when a component is undeployed, its underlying data will also be deleted

Responses

Request samples

Content type
application/json
Example
{
  • "descriptorKind": "DATAPRODUCT_DESCRIPTOR",
  • "descriptor": "dataProduct:\n id: urn:dmb:dp:finance:a-system:0\n components: \n - id: urn:dmb:dp:finance:a-system:0:component:0\n name: S3 storage\n description: A system that does something\n kind: storage\n version: 0.0.1\n - id: urn:dmb:dp:finance:a-system:0:component:1\n name: A system that does something\n description: A system that does something\n kind: outputport\n version: 0.0.1\nremoveData: false",
  • "removeData": false
}

Response samples

Content type
application/json
Example
{
  • "status": "COMPLETED",
  • "info": {
    }
}

Get the status of a provision/unprovision task

Get the status and the results of a provision/unprovision operation.

This endpoint is used by the Provisioning Coordinator to poll the status of a provision/unprovision task.

path Parameters
token
required
string
Example: 3da5d0a2-9f3b-4a11-85a3-b5ddb73da032

Provisioning Task Token obtained after a call to the provision or unprovision endpoints

Responses

Response samples

Content type
application/json
Example
{
  • "status": "RUNNING"
}

Stop provision/unprovision task

Terminate a provision/unprovision task that is still running.

The tech adapter will use a request coming at this endpoint as a signal to stop the task. The provisioning coordinator will continue to poll the status of a provision/unprovision task by using the token that was returned by the provision/unprovision endpoint and not the one returned here.

The task can be stopped only if the tech adapter supports it, otherwise a 501 error is returned.

path Parameters
token
required
string
Example: 3da5d0a2-9f3b-4a11-85a3-b5ddb73da032

Provision/Unprovision Task Token obtained after a call to the provision/unprovision endpoint

Responses

Response samples

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

Upsert the Access Control List

Create or update the Access Control List of an infrastructural component with the provided identities.

The supplied list of identities refers to the users and groups that need to have access to the component.

This means, Witboost always supplies the full list of identities even if some of them already have access to the underlying infrastructural resource.

Request Body schema: application/json
required
refs
required
Array of strings

Identities (i.e. users and groups) that should be registered in the Access Control List of the target component.

The format of identities follows the Witboost format. Users are prefixed with user: and groups with group:.

required
object (ProvisionInfo)

Information related to the provisioning workflow of a system

accessControlFields
object

A free-form object that can be used to store additional information about the access control list request.

These values are supplied from the user when using an Access Control Request Template on the UI.

Responses

Request samples

Content type
application/json
{
  • "refs": [
    ],
  • "provisionInfo": {
    },
  • "accessControlFields": {
    }
}

Response samples

Content type
application/json
Example
{
  • "status": "COMPLETED",
  • "info": {
    }
}

Import an existing resource

Import an existing resource from the infrastructure into Witboost.

This operation is used to reverse provision a component that is already deployed in the target environment.

The reverse provisioning operation is used to import the current state of the component into Witboost, so that it can be tracked by the platform.

Request Body schema: application/json
required
useCaseTemplateId
required
string

Component's use case template id

environment
required
string

Target environment

params
object

Reverse provisioning input params

catalogInfo
object

Content of the current catalog-info.yaml of the component

Responses

Request samples

Content type
application/json
{
  • "useCaseTemplateId": "urn:dmb:utm:aws-s3-object:0",
  • "environment": "development"
}

Response samples

Content type
application/json
Example
{
  • "status": "COMPLETED",
  • "updates": {
    },
  • "logs": [
    ]
}

Get status of an import task

Get the status and the results of a reverse provisioning operation.

The reverse provisioning operation is used to import the current state of the component into Witboost, so that it can be tracked by the platform.

path Parameters
token
required
string
Example: 3da5d0a2-9f3b-4a11-85a3-b5ddb73da032

Reverse Provisioning Task Token obtained after a call to the import endpoint

Responses

Response samples

Content type
application/json
Example
{
  • "status": "RUNNING"
}