Skip to main content
API docs by Redocly

Witboost Extension Points API

Overview

Witboost is an extensible platform which give developers the possibility to bring in their own technologies and organizational processes.

This requires the implementation of specific extension points API contracts that are listed here. Before proceeding into the implementation of any of those, please take a look also at the Witboost Starter Kit which is a comprehensive set of open source integrations that are available out-of-the-box, leaving you with just the deployment of those integrations in your infrastructure.

Through this page you will be able to better understand the extension points that are available in the Witboost platform.

Extension Points

Extension points can be classified into these categories.

Provisioning Experience extension points:

  • Tech Adapter API: integrates a specific technology into Witboost
  • Data Catalog Plugin API: provision and unprovision metadata into a third-party Data Catalog during the deployment phase of a resource through Witboost
  • Marketplace Plugin API: publish resources in the Witboost Marketplace or to third-party marketplaces.

Governance Experience extension points:

  • Remote Engine API: handle requests from the Computational Governance Platform to validate resources using any language or runtime of your choice.
  • Perimeter Resolver API: supply resources to the Computational Governance Platform from catalogs or entities repositories.

Platform Experience extension points:

  • Custom URL Picker API: provide selectable options to templates through the use of the Custom URL Picker.
  • Webhook Notifications API: send notifications to external services when specific events occur in Witboost.
  • Remote Request Hook API: forward access control requests, or other requests which require third-party approvals, to an external ticketing system for evaluation.

Tech Adapter API

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.

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
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
"3da5d0a2-9f3b-4a11-85a3-b5ddb73da032"

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
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
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
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 catalog format. Users are prefixed with user: and groups with group:.

required
object

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"
}

Data Catalog Plugin API

A Data Catalog Plugin is a microservice that is responsible for provisioning and unprovisioning metadata into a Data Catalog during the deployment phase of a resource through Witboost.

It takes in a system descriptor enriched with components' provisioning results and returns the result of the provisioned Data Catalog entities.

The Data Catalog contract is similar to a technology adapter, with a few differences. It takes in the whole system descriptor already enriched with tech adapters' deploy info.

Validate a Data Catalog Entity provision request (async)

Validate output ports metadata attached in the provisioning request.

In particular, it validates the format and the existence of glossary terms and classification tags

Request Body schema: application/json
required

Details of a provisioning request to be validated

descriptorKind
required
string
Enum: "DATAPRODUCT_DESCRIPTOR" "DATAPRODUCT_DESCRIPTOR_WITH_RESULTS"
descriptor
required
string

A provisioning request in yaml format

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
"2f4b3b3b-4b3b-4b3b-4b3b-4b3b4b3b4b3b"

Get status of an async validation task

path Parameters
token
required
string
Example: 2a4bb060-27c9-403d-ab5d-d3776cf56c3b

Token obtained after a call to the async validate endpoint

Responses

Response samples

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

Validate a Data Catalog Entity provision 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
Enum: "DATAPRODUCT_DESCRIPTOR" "DATAPRODUCT_DESCRIPTOR_WITH_RESULTS"
descriptor
required
string

A provisioning request in yaml format

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
{
  • "valid": true
}

Provision Data Catalog entity

Provisioning is the operation that deploys the metadata of a system or a single component into a third-party Data Catalog.

This request can be handled in synchronous or asynchronous mode depending on the implementation.

Request Body schema: application/json
required

A Data Product descriptor, enriched with components' provisioning results, wrapped as a string into a simple object

descriptorKind
required
string
Enum: "DATAPRODUCT_DESCRIPTOR" "DATAPRODUCT_DESCRIPTOR_WITH_RESULTS"
descriptor
required
string

A provisioning request in yaml format

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
{
  • "status": "COMPLETED",
  • "info": {
    }
}

Unprovision Data Catalog entity

Unprovisioning is the operation that removes the metadata of a system or a single component from a third-party Data Catalog.

This request is synchronous and returns the result of the unprovisioning process.

Request Body schema: application/json
required

A system descriptor and the provisioning results wrapped as simple object

descriptorKind
required
string
Enum: "DATAPRODUCT_DESCRIPTOR" "DATAPRODUCT_DESCRIPTOR_WITH_RESULTS"
descriptor
required
string

A provisioning request in yaml format

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
{
  • "status": "COMPLETED",
  • "info": {
    }
}

Get status of Data Catalog entity provision/unprovision task

path Parameters
token
required
string
Example: f6440015-1404-4e96-a250-7f680dbc32d4

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

Responses

Response samples

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

Get linked Data Catalog entity

Return the reference (id, links, etc) to the Data Catalog entity that refers to the provided Output Port

query Parameters
componentId
required
string
Example: componentId=urn:dmb:dp:finance:a-system:0:component:1

Output Port URN to get the reference to the Data Catalog entity

Responses

Response samples

Content type
application/json
{}

Marketplace Plugin API

A Marketplace Plugin is the component responsible to publish resources into the Witboost Marketplace or third-party marketplaces.

It is also responsible to mantain alignment between the Access Control List on the infrastructural component and on the UI.

Publish a resource into the Marketplace

Insert the latest provisioning result and descriptor into the target marketplace registry.

Request Body schema: application/json
required

An asset descriptor and the provisioning results wrapped as simple object

descriptor
required
string

Asset descriptor in yaml format

Responses

Request samples

Content type
application/json
{
  • "descriptor": "string"
}

Response samples

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

Remove a resource from the Marketplace

Perform a delete operation of asset descriptor references that are in the Marketplace DB

Request Body schema: application/json
required

An asset descriptor and the provisioning results wrapped as simple object

descriptor
required
string

Asset descriptor in yaml format

Responses

Request samples

Content type
application/json
{
  • "descriptor": "string"
}

Response samples

Content type
application/json
"string"

Sync the Access Control List

Update the Access Control List table copy that is kept in the Marketplace.

Request Body schema: application/json
required

The request used to update the ACL table.

requestId
required
string
outputPortId
required
integer
refs
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "requestId": "string",
  • "outputPortId": 0,
  • "refs": [
    ]
}

Response samples

Content type
application/json
"string"

Custom URL Picker API

A Custom URL Picker is a picker that can be used inside Witboost templates to ask information to end users through a drop-down menu.

The options of the drop-down menu can be supplied by a microservice implementing this Custom URL Picker API specification.

The microservice will be called by the Custom URL Picker to get the options to show to the user in the drop-down list on the UI. The user can filter out results by typing in the Custom URL Picker field. The microservice will return the first limit elements that match the filter, skipping the first offset elements.

Retrieve drop-down list options

Called by the Custom URL Picker to get the options to show to the user in the drop-down list on the UI.

The user can filter out results by typing in the Custom URL Picker field. The microservice will return the first limit elements that match the filter, skipping the first offset elements.

query Parameters
filter
string
Example: filter=banana

The user input, that is typed by the user on the UI field, which is used to filter the values on the glossary.

If not provided, the microservice will return all the values in the glossary following the pagination settings.

offset
required
number
Example: offset=0

the number of values to skip for each request

limit
required
number >= 5
Example: limit=5

the number of values to return at each request

Request Body schema: application/json
optional

A free-form object that can be used to define additional properties to use while performing a search in the glossary. This can be filled with other fields values coming from the template.

object

Responses

Request samples

Content type
application/json
{
  • "kind": "fruit"
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Validate a selected option against the glossary

Called by the Custom URL picker to validate the selected values against the ones included in the glossary e.g. for checking if the selected values are still present in the glossary.

This API gets called when the user wants to modify some values e.g. by using the Edit Template, and a check is being run to see if the previously selected value is still present in the glossary with the exact shape.

Request Body schema: application/json
required
Array of objects

the selected options to validate

queryParameters
object

This field represents additional parameters to put in the request body. The user can use it to define additional properties to use while performing a validation on the "selectedObject".

Responses

Request samples

Content type
application/json
{
  • "selectedObjects": [
    ],
  • "queryParameters": {
    }
}

Response samples

Content type
application/json
"Validation succeded"

Webhook Notifications API

By implementing the Webhook Notifications API, you will be able to receive notifications about events happened within the Witboost platform.

The Webhook Notifications API is helpful for integrating with third-party messaging systems like Microsoft Teams, Slack, Discord etc.

As you will notice from this API specification, there is no API endpoint to implement, but rather just a JSON schema which represents what the payload of a notification looks like. This payload is what your configured webhook URL is going to receive at the POST endpoint.

The JSON schema is described in this page here: Webhook Notifications JSON Schema

Remote Request Hook API

A Remote Request Hook receive approvals request from Witboost such that they can be forwarded to third-party ticketing systems.

As an example, with the Remote Request Hook, you can handle Access Control requests from outside Witboost.

Send approval request

Receive a request from witboost about an ongoing action started by a user that requires a third-party interaction on your end

header Parameters
X-Request-ID
required
string <uuid>
Examples:
  • 6bba34a3-173e-4100-9ccb-5b63035cc86a -

A unique identifier for the request that can be used to trace the request in the logs.

Request Body schema: application/json
required

An object containing all the input data received by the action where the remote request hook is attached

respondToUrl
required
string

URL to be contacted to notify that the hook is completed. This represents the fact that the third-party interaction has been performed on your end. e.g. An access request that has been accepted on your dedicated platform

fields
required
object

A free-form object containing all the action's input data coming from witboost

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
Example
{
  • "hookInfo": {
    }
}

Remote Engine API

A Remote Engine is a service responsible to manage requests from the Computational Governance Platform to validate resources.

By implementing this API contract, the service will be able to receive requests to evaluate resources and return the result of the evaluation compliant to the Computational Governance Platform results.

This gives developers the possibility to implement their own validation logic with any technology of their choice, as long as it respects the API contract.

Register a Remote Engine

Once you develop and deploy a microservice that implements the Remote Engine API, when you create a policy or metric in Witboost, you can select the Remote Engine to use for the evaluation.

When you select Remote Engine, you will be able to provide the URL of the service that implements this API contract. Make sure the service is reachable by the Witboost platform.

Evaluate a resource

Computes a result based on the input resource. The result can be a policy result or a metric result.

Request Body schema: application/json
required

An object containing the resource to evaluate using this executor

content
required
string

The content of the resource to be evaluated. The content can be any type of data, such as a JSON object, a string, a number, etc but always in its string representation. e.g. For a system resource, the content will be a stringified YAML descriptor.

resourceType
required
string

Resource type that is being sent in the content. This has to be agreed between the Remote Engine implementation and the platform's registered resource types.

resourceId
required
string

A unique Resource Identifier inside the Witboost platform.

Responses

Request samples

Content type
application/json
Example
{
  • "content": "apiVersion: v1\nkind: System\nmetadata:\n name: my-system\n namespace: my-namespace\n labels:\n app: my-app",
  • "resourceType": "system",
  • "resourceId": 123456
}

Response samples

Content type
application/json
Example
{
  • "satisfiesPolicy": false,
  • "errors": [
    ],
  • "details": {
    }
}

Perimeter Resolver API

A Perimeter Resolver is a microservice responsible to supply resources to the Computational Governance Platform.

When a policy or metric is being run from Witboost, the Perimeter Resolver gets invoked to get a list of resources of the policy/metric declared resource type together with additional filters.

Perimeter Resolver fetches resources for which is responsible to from an underlying storage or catalog. The resources are filtered based on the environment and the resource type.

Register a Perimeter Resolver

Once you develop a microservice that implements the Perimeter Resolver API, you can register it with the Computational Governance Platform API. The registration process requires an HTTP call to this API.

Retrieve resources

query Parameters
environment
required
string
Example: environment=development

Environment where to look for resources

resource-types
string
Example: resource-types=type1,type2,type3

Comma-separated list of resource types to filter on. Ignored if the perimeter resolver doesn't provide more than one resource type

id
string
Example: id=rf2e-3f2f-3f2f-3f2f

A resource id to retrieve

offset
integer
Default: 0
Example: offset=0

Number of resources to skip before retrieving data. Used for pagination.

limit
integer <= 50
Default: 5
Example: limit=5

Maximum number of resources to retrieve. Used for pagination.

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": {
    }
}