Defined Interfaces

Interfaces represent categories of Defined Entity definitions.

For example, a ContainerCluster interface could represent the concept of a Cluster of Containers. Multiple Defined Entity Types may implement that interface, each representing a different type of Container Cluster.

Interfaces can also specify custom defined actions called behaviors that can be used to perform operations on Defined Entities of the corresponding categories.

For example, a ContainerCluster interface could define an addNode behavior. Defined Entity Types implementing the interface can either use the default addNode behavior definition in the interface or they can override it to make it specific to their implmentation.

Definition

An example simple interface definition:

{
    "name": "Container Cluster",
    "vendor": "clusterVendorA",
    "nss": "containerCluster",
    "version": "1.0.0"
}

The properties nss, vendor, and version uniquely identify the interface. Once the interface is created, these properties cannot be modified.

Example API calls

Create an interface

A new interface can be created by authorized clients via an API call. For example:

POST /cloudapi/1.0.0/interfaces

{
    "name": "Container Cluster",
    "vendor": "clusterVendorA",
    "nss": "containerCluster",
    "version": "1.0.0"
}

Response:

{
    "name": "Container Cluster",
    "id": "urn:vcloud:interface:clusterVendorA:containerCluster:1.0.0",
    "vendor": "clusterVendorA",
    "nss": "containerCluster",
    "version": "1.0.0",
    "readonly": false
}

The id field in the response represents how the interface will be referenced in other API requests.

The readonly flag is added automatically to the interface representation and indicates whether the definition is custom or built-in. It cannot be set via the API.

Update an interface

An interface can be updated by authorized clients via an API call. For example:

PUT /cloudapi/1.0.0/interfaces/<interface-id>

{
    "name": "Cluster of Containers",
    "vendor": "clusterVendorA",
    "nss": "containerCluster",
    "version": "1.0.0"
}

Response:

{
    "name": "Cluster of Containers",
    "id": "urn:vcloud:interface:clusterVendorA:containerCluster:1.0.0",
    "vendor": "clusterVendorA",
    "nss": "containerCluster",
    "version": "1.0.0",
    "readonly": false
}

An interface cannot be updated if it is in use. An interface is in use if there is at least one RDE instance created in any of the RDE Types which implement the interface.

Add a behavior to an interface

Intefaces can define a set of RDE Behaviors. Behaviors are typically specified as part of the interface definition.

Behaviors can also be added to the interface individually or as a set.

POST /cloudapi/1.0.0/interfaces/<interface-id>/behaviors

{
    "name": "addNode",
    "execution" : {
        "type": ...,
        ...
    }
}

Response:

{
    "name": "addNode",
    "id": "urn:vcloud:behavior-interface:addNode:clusterVendorA:containerCluster:1.0.0",
    "ref": "urn:vcloud:behavior-interface:addNode:clusterVendorA:containerCluster:1.0.0",
    "execution": {
        "type": ...,
        ...
    }
}

The id and ref fields in the response represent how the specific behavior can be referenced in other API requests. The difference between them is explained in the behavior id section.

The behaviors of an interface cannot be updated if the interface is in use. An interface is in use if there is at least one RDE instance created in any of the RDE Types that implement the interface.

Delete an interface

An interface can be updated by authorized clients via an API call.

DELETE /cloudapi/1.0.0/interfaces/<interface-id>

An interface cannot be deleted if it is in use. An interface is in use if there is at least one RDE instance created in any of the RDE Types which implement the interface.

Access to Defined Interface Operations

Operation	Required Right
View and query interface	All users have the necessary rights.
Create interface	Create new custom entity definition
Edit interface	Edit custom entity definition
Delete interface	Delete custom entity definition
View and query interface behaviors	View custom entity definitions
Create a new behavior in interface	Create new custom entity definition
Update behavior in interface	Edit custom entity definition
Delete behavior in interface	Edit custom entity definition