REST API

The Solution Manager REST API defines a set of functions which developers can invoke via HTTP protocol. The requests and responses use JSON format (JavaScript Object Notation). In order to receive and send JSON media type, you should configure the HTTP client to include the Accept header (for receiving the data) and the Content-Type header (for sending the data):

Accept: application/json
Content-Type: application/json

Note

For simplification, the HTTP requests of this document only include relevant HTTP headers, other headers are omitted. For example, the User-Agent header can have any value and it is not included in the examples.

The list of supported actions that you can execute using HTTP requests (GET, POST or DELETE), are the following:

Creating a Session with the Solution Manager

Solution Manager REST API supports two authentication methods: basic HTTP authentication and Single Sign-On authentication using Kerberos.

1. Creating a Session Using HTTP Basic Authentication

  • URL: /login

  • Method: GET

  • Required headers:

    • Authorization: basic HTTP authentication.
    • Accept: this header must include application/json media type in the list of supported formats.
Authorization: Basic <text>  /* base64 encoded of user:password */
Accept: application/json

The following example shows an HTTP request to login the user admin with password admin:

GET /login HTTP/1.1
Authorization: Basic YWRtaW46YWRtaW4=
Accept: application/json

If the user credentials are correct, Solution Manager sends the HTTP status code 200. In this case, the response body contains the user roles in JSON format.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Set-Cookie: JSESSIONID=<cookie>;path=/;HttpOnly

{
    "userName": <text>,
    "promotionAdmin": <bool>,
    "admin": <bool>,
    "jmxadmin": <bool>
}

The following example shows the response sent by the Solution Manager when the authentication of the admin user was successful.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Set-Cookie: JSESSIONID=347C78C0446F03FBE4468A10F1F55A7A;path=/;HttpOnly

{
    "userName": "admin",
    "promotionAdmin": true,
    "admin": true,
    "jmxadmin": true
}

JSESSIONID cookie identifies the session. When the session has already being created, your next requests must include JSESSIONID in the Cookie header.

GET /environments HTTP/1.1
Cookie: JSESSIONID=347C78C0446F03FBE4468A10F1F55A7A
Accept: application/json

If the login request fails, the Solution Manager sends the HTTP error code (4xx or 5xx). In addition, the response body includes the error code and the error message in JSON format, according to the following format.

HTTP/1.1 <status>
Content-Type: application/json;charset=UTF-8

{
    "status" : <number>,
    "message" : <text>
}

For example, if the credentials are invalid, the server sends the status code 401 unauthorized.

HTTP/1.1 401
Content-Type: application/json;charset=UTF-8

{
    "status" : 401,
    "message" : "The user name or password is incorrect"
}

2. Creating a Session Using Single Sign-On with Kerberos

  • URL: /loginSingleSignOn
  • Method: GET
  • Required headers:
    • Authorization: Kerberos token.
    • Accept: application/json media type must be included.
Authorization: <text> /* Kerberos Token */
Accept: application/json

The response types for the Kerberos authentication are the same as the response types for the basic HTTP authentication.

Close a Session with the Solution Manager

  • URL: /logout
  • Method: GET
  • Required headers:
    • Cookie: JSESSIONID cookie.
    • Accept: application/json media type must be included.

If the session has been successfully closed, the server sends the status code 200 with an empty response body.

GET /logout HTTP/1.1
Cookie: JSESSIONID=347C78C0446F03FBE4468A10F1F55A7A
Accept: application/json

Note

The required headers (Cookie, Content-Type and Accept) are omitted for clarity.

Get the List of Environments

You can get the list of environments defined in the Solution Manager executing the following request:

  • URL: /environments
  • Method: GET

If the request has been successfully executed, the server sends the status code 200. The response body includes the list of environments in JSON format. Each environment can contain the following information:

{
    "id": <number>,
    "name": <text>,
    "description": <text>,
    "minimumUpdateValue":<number>  /* format yyyymmdd */,
    "minimumUpdateMandatory": <bool> /* the minimum update is mandatory in the Virtual DataPort Administration Tool */,
    "minimumUpdateDownloadUrl": <URL>,
    "licenseAlias": <text>
}

The following example represents a list of 2 environments.

[
    {
        "id": 1,
        "name": "Environment 1",
        "description": "First environment",
        "minimumUpdateMandatory": false,
        "licenseAlias": "PRODUCTION"
    },
    {
        "id": 2,
        "name": "Environment 2",
        "description": "Second environment",
        "minimumUpdateMandatory": false,
        "licenseAlias": "DEVELOPMENT"
    }
]

Get the List of Virtual DataPort Properties Associated to an Environment

The following URL returns the list of environment properties for a given environment:

  • URL: /environments/{number:environmentId}/vdpProperties

  • Method: GET

  • Parameters:

    • propertyName: this parameter specifies an exact property name.
    • databaseName: this parameter filters properties by database name.
    • elementType: this parameter filters properties by element type (for example, view or data source).
    • elementTypeName: this parameter filters properties by element type name (for example, JDBC, XML, etc.).
    • elementName: this parameter filters properties by element name.

The URL path must include the environment identifier. The following URL returns the Virtual DataPort properties for the environment with the identifier 3.

GET /environments/3/vdpProperties

The response body includes the list of environment properties.

{
    "environmentProperties": [
        {
            "id": <number>,
            "name": <text>,
            "value": <text>,
            "propertyType": "VDP",
            "parentId": <number>
        },
        { ... }
   ]
}

The following example represents a response which returns 3 properties for the environment with identifier 3.

 {
     "environmentProperties": [
         {
             "id": 30,
             "name": "users.smadmin.PASSWORD",
             "value": "mYgfbAayggeImPPOGfklFLfgt ...",
             "propertyType": "VDP",
             "parentId": 3
         },
         {
             "id": 32,
             "name": "users.smadmin.PASSWORD.ALGORITHM",
             "value": "SHA512",
             "propertyType": "VDP",
             "parentId": 3
         },
         {
             "id": 31,
             "name": "users.smadmin.PASSWORD.ENCRYPTED",
             "value": "ENCRYPTED",
             "propertyType": "VDP",
             "parentId": 3
         }
     ]
}

Optional request parameters to filter environment properties

The following URL specifies the parameter propertyName and returns a Virtual DataPort property with name users.smadmin.PASSWORD.ALGORITHM.

GET /environments/2/vdpProperties?propertyName=users.smadmin.PASSWORD.ALGORITHM

Note

If propertyName is specified, the other parameters are ignored.

The parameter databaseName filters properties by database. The following URL returns all properties matching database.admin.*

GET /environments/2/vdpProperties?databaseName=admin

The parameter elementType filters properties by element type. The following URL returns all properties matching database.*.datasource.*. Example: databases.admin.datasources.jdbc.oracle12c.DATABASEURI.

GET /environments/2/vdpProperties?elementType=datasources

The parameter elementTypeName filters properties by element type name. The following URL returns all properties related with JDBC. Examples: databases.admin.views.jdbc.environment.SCHEMANAME and databases.admin.datasources.jdbc.oracle12c.USERNAME

GET /environments/2/vdpProperties?elementTypeName=jdbc

The parameter elementName filters properties by element name. The following URL returns the properties of the data source with name oracle12c.

GET /environments/2/vdpProperties?elementName=oracle12c

Except the parameter propertyName, the others can be combined in the same request. For example, the following URL returns all properties of the LDAP data sources of the database admin.

GET /environments/2/vdpProperties?databaseName=admin&elementType=datasources&elementTypeName=ldap

Create and Delete Environment Properties

If you execute a POST request to the following URL you can create an environment property:

  • URL: /environments/{number:environmentId}/vdpProperties
  • Method: POST

The request body must include the list of properties, according to the following format:

[
   {
        "name" : <text>
        "value" : <text>
   },
   { ... }
]

The next example shows a POST request which creates 3 properties:

[
    {
        "name": "users.smadmin.PASSWORD",
        "value": "mYgfbAayggeImPPOGfklFLfgt2Azb/5TVjDtYQChCE29k6tjDru7 ... "
    },
    {
        "name": "users.smadmin.PASSWORD.ALGORITHM",
        "value": "SHA512"
    }
]

The response body contains the new properties with their identifiers:

[
    {
        "id": 30,
        "name": "users.smadmin.PASSWORD",
        "value": "mYgfbAayggeImPPOGfklFLfgt2Azb/5TVjDtYQChCE29k6tjDru7 ... "
    },
    {
        "id": 32,
        "name": "users.smadmin.PASSWORD.ALGORITHM",
        "value": "SHA512"
    }
]

If you send a DELETE request to the following URL, you can delete an environment property:

  • URL: /vdpProperties/{number:vdpPropertyId}
  • Method: DELETE

The next example deletes a property with the identifier 5:

DELETE /vdpProperties/5

If the property has been successfully deleted, the response status code is 204.

Get the List of Clusters

The following request returns the list of clusters of an environment:

  • URL: /environments/{number:environmentId}/clusters
  • Method: GET

If the request has been successfully executed, the server sends the status code 200. The response body includes the list of clusters in JSON format. Each cluster can contain the following information:

{
    "clusters": [
        {
            "id": <number>,
            "name": <text>
        },
        { ... }
    ]
}

The following example return a list with 2 clusters.

{
    "clusters": [
        {
            "id": 7,
             "name": "Cluster 2"
        },
        {
            "id": 8,
             "name": "Cluster 3"
        }
    ]
}

Get the List of Scheduler Properties Associated to a Cluster

The following URL returns the list of Scheduler properties for a given cluster:

  • URL: /clusters/{number:clusterId}/schProperties

  • Method: GET

  • Parameters:

    • propertyName: this parameter specifies an exact property name.
    • projectName: this parameter filters properties by project name.
    • elementType: this parameter filters properties by element type (for example, data source).
    • elementTypeName: this parameter filters properties by element type name (for example, VDP).
    • elementName: this parameter filters properties by element name.

The URL path must include the cluster identifier. The following URL returns the Virtual DataPort properties for the cluster with the identifier 3.

GET /cluster/3/schProperties

Optional Request Parameters to Filter Cluster Properties

The following URL specifies the parameter propertyName and returns a Scheduler property with name SolutionManager.dataSource.ITP.itpds.dbName.

GET /clusters/4/schProperties?propertyName=SolutionManager.dataSource.ITP.itp.dbName

Note

If propertyName is specified, the other parameters are ignored.

The parameter projectName filters properties by project. The following URL returns all properties matching SolutionManager.*

GET /clusters/2/schProperties?projectName=SolutionManager

The parameter elementType filters properties by element type. The following URL returns all properties matching *.datasource.*. Example: SolutionManager.dataSource.ITP.itpds.host.

GET /clusters/2/schProperties?elementType=datasource

The parameter elementTypeName filters properties by element type name. The following URL returns all properties related with ITP. Example: SolutionManager.dataSource.ITP.itpds.host.

GET /clusters/2/schProperties?elementTypeName=ITP

The parameter elementName filters properties by element name. The following URL returns the properties of the data source named itpds.

GET /clusters/2/schProperties?elementName=itpds

Except the parameter propertyName, the others can be combined in the same request. For example, the following URL returns all data source properties of the project SolutionManager.

GET /clusters/2/schProperties?projectName=SolutionManager&elementType=datasource

Create and Delete Cluster Properties

You can execute a POST request to the following URL to create cluster properties:

  • URL: /clusters/{number:cluserId}/schProperties
  • Method: POST

The request body must include the list of properties according to the following format:

[
   {
        "name" : <text>
        "value" : <text>
   },
   { ... }
]

The next example shows a POST request which creates 2 properties:

[
    {
        "name": "default.dataSource.VDP.vdp.connectionURI",
        "value": "//localhost:19999/admin"
    },
    {
        "name": "default.dataSource.VDP.vdp.login",
        "value": "admin"
    }
]

The response body includes the created properties with their identifiers.

[
    {
        "id": 34,
        "name": "default.dataSource.VDP.vdp.connectionURI",
        "value": "//localhost:19999/admin"
    },
    {
        "id": 35,
        "name": "default.dataSource.VDP.vdp.login",
        "value": "admin"
    }
]

If you send a DELETE request to the following URL, you can delete a cluster property:

  • URL: /schProperties/{number:schPropertyId}
  • Method: DELETE

The next example deletes a property with identifier 5:

DELETE /schProperties/5

If the property has been successfully deleted, the response status code is 204.

Get the List of Revisions

The following URL returns the list of revisions:

  • URL: /revisions

  • Method: GET

  • Parameters:

    • start: this parameter specifies the first element of the collection to be returned.
    • count: this parameter specifies the maximum number of results to be returned.

The response body includes the list of revisions according to the following format:

{
    "start": <number>, /* specifies the first revision of the collection to be returned */
    "count": <number>, /* maximum number of revisions to be returned */
    "numElements": <number>, /* total number of revisions included in the response */
    "revisions": [
        {
            "id": <number>,
            "description": <text>,
            "name": <text>,
            "type": ["INSERT" | "DELETE"], /* alias for CREATE and DROP */
            "replace": ["DO_NOT_REPLACE_EXISTING" | "REPLACE_EXISTING" | "DROP_ELEMENTS_BEFORE"],
            "creationUser": <text>,
            "creationTime": <date>, /* date format: yyyy-MM-dd'T'HH:mm:ss.SSZ */
            "lastModifiedUser": <admin>,
            "lastModifiedTime": <date>, /* date format: yyyy-MM-dd'T'HH:mm:ss.SSZ */
            "hasVql": <bool>,
            "hasScheduler": <bool>,
            "includeJars": <bool>,
            "includeStatistics": <bool>,
            "useDefaultDatabase": <bool>,
            "deployedOn": [ /* list of environments in which the revision was already deployed */
                {
                    "id": <number>,
                    "name": <text>,
                    "description": <text>,
                    "minimumUpdateMandatory": <bool>
                },
                { ... }
            ]
        },
        { ... }
    ]
}

The following example represents two revisions in JSON format. The first one was deployed on 2 environment, the second one was not deployed on any environment:

{
   "start": 0,
   "count": 10,
   "numElements": 2,
   "revisions": [
        {
            "id": 3,
            "description": "Third revision",
            "name": "Revision 3",
            "type": "INSERT",
            "replace": "DO_NOT_REPLACE_EXISTING",
            "creationUser": "smadmin",
            "creationTime": "2017-11-11T00:15:34.507+0000",
            "lastModifiedUser": "smadmin",
            "lastModifiedTime": "2017-11-11T00:15:34.507+0000",
            "hasVql": true,
            "hasScheduler": false,
            "includeJars": false,
            "includeStatistics": false,
            "useDefaultDatabase": true,
            "deployedOn": [
                {
                    "id": 2,
                    "name": "Environment 2",
                    "description": "Second environment",
                    "minimumUpdateMandatory": false
                },
                {
                    "id": 3,
                    "name": "Environment 3",
                    "description": "Third environment",
                    "minimumUpdateMandatory": false
                }
            ]
        },
        {
            "id": 2,
            "description": "Second revision",
            "name": "Revision 2",
            "type": "DELETE",
            "replace": "DROP_ELEMENTS_BEFORE",
            "creationUser": "smadmin",
            "creationTime": "2017-11-11T00:15:34.429+0000",
            "lastModifiedUser": "smadmin",
            "lastModifiedTime": "2017-11-11T00:15:34.429+0000",
            "hasVql": true,
            "hasScheduler": false,
            "includeJars": false,
            "includeStatistics": false,
            "useDefaultDatabase": true
        }
    ]
}

Get the List of Deployments

The following URL returns the list of deployments:

  • URL: /deployments

  • Method: GET

  • Parameters:

    • start: this parameter specifies the first deployment of the collection to be returned.
    • count: this parameter specifies the maximum number of deployments to be returned.
    • environmentId: this parameter filters deployments by target environment.
    • status: this parameter filters deployments by execution status (OK, ERROR, IN_PROGRESS).
    • description: this parameter filters deployments by description.
    • user: this parameter filters deployments by user.
    • startDeploymentTime: this parameter filters deployments by start deployment time. Date format is yyyy-MM-dd’T’HH:mm:ssZ.
    • endDeploymentTime: this parameter filters deployments by end deployment time. Date format is yyyy-MM-dd’T’HH:mm:ssZ.

The response body includes the deployments in JSON format, according to the following template:

{
    "start": <number>,
    "count": <number>,
    "numElements": <number>,
    "deployments": [
        {
            "id": <number>,
            "user": <text>,
            "deploymentTime": <date>, /* date format: yyyy-MM-dd'T'HH:mm:ss.SSZ */
            "description": <text>,
            "state": ["OK" | "ERROR" | "IN_PROGRESS"]
            "targetEnvironment": {
                "id": <number>,
                "name": <text>,
            },
            "revisions": [
                {
                    "id": <number>,
                    "description": <text>,
                    "name": <text>
                },
                { ... }
            ],
        },
        { ... }
    ]
}

The following example returns a list of 2 deployments:

{
    "start": 0,
    "count": 10,
    "numElements": 2,
    "deployments": [
        {
            "id": 28,
            "user": "admin",
            "deploymentTime": "2017-11-12T23:05:53.179+0000",
            "description": "",
            "targetEnvironment": {
               "id": 3,
               "name": "Environment 3",
             },
            "revisions": [
                {
                    "id": 3,
                    "description": "Third revision",
                    "name": "Revision 3"
                }
            ],
            "state": "OK"
        },
        {
            "id": 27,
            "user": "admin",
            "deploymentTime": "2017-11-12T23:05:40.838+0000",
            "description": "",
            "targetEnvironment": {
                "id": 3,
                "name": "Environment 3",
            },
            "revisions": [
                {
                    "id": 3,
                    "description": "Third revision",
                    "name": "Revision 3"
                }
            ],
            "state": "OK"
        }
    ]
}

The following URL returns the list of deployments between 2017-11-07T16:50:32+0100 and 2017-11-15T16:50:33+0100. You must specify both parameters, startDeploymentTime and endDeploymentTime, together.

GET /deployments?startDeploymentTime=2017-11-07T16%3A50%3A32%2B0100&endDeploymentTime=2017-11-15T16%3A50%3A33%2B0100

The following URL returns the list of deployments in progress.

GET /deployments?status=IN_PROGRESS

Start a New Deployment from a List of Revisions

You can execute a new deployment sending a POST request to the following URL:

  • URL: /deployments
  • Method: POST

The request body must follow the template below.

{
    "revisionIds": [ <number>, ... ],
    "environmentId": <number>,
    "description": <text>
}

This request must include the list of revision identifiers (revisionIds) and also the identifier of the target environment (environmentId). The following example creates a deployment from the revisions 1 and 2, on the target environment identified with the id 3.

{
    "revisionIds": [1, 2],
    "environmentId": 3,
    "description": "My first deployment"
}

It the deployment has been successfully created, the response body returns the numeric deployment identifier.

Get the Progress of a Deployment

The following URL returns the deployment status and the list of deployment tasks:

  • URL: /deployments/{number:deploymentId}/progress

  • Method: GET

  • Parameters

    • lastUpdate: filters deployment tasks by last update date.

The response body includes the deployment progress and the list of deployment tasks according to the following template:

{
    "deploymentId": <number>,
    "state": ["OK" | "ERROR" | "IN_PROGRESS"],
    "progress": <number>, /* percent between 0 and 100 */
    "tasks": [
        {
            "id": <number>,
            "name": <text>,
            "state": ["OK" | "ERROR" | "IN_PROGRESS"],
            "startDate": <date>,
            "endDate": <date>,
            "deploymentExecutionType": <text>,
            "output": <text>,
            "cluster": {
                "id": <number>,
                "name": <text>
            },
            "server": {
                "id": <number>,
                "name": <text>
            }
        },
        { ... }
    ]
}

The optional request parameter lastUpdate filters tasks by last update date. If it is specified, the response body only include tasks modified since this date.

The following example shows an example of deployment progress with 1 execution task:

{
    "deploymentId": 1,
    "state": "OK",
    "progress": 100,
    "tasks": [
        {
            "id": 1,
            "name": "Revision Revision 1 VQL deployment",
            "state": "OK",
            "startDate": "2017-11-13T11:18:40.999+0000",
            "endDate": "2017-11-13T11:18:41.065+0000",
            "deploymentExecutionType": "VQL",
            "output": " - Executed 1 of 1 VQL commands",
            "cluster": {
               "id": 7,
               "name": "Cluster 2"
            },
            "server": {
                "id": 8,
                "name": "Server 3"
            }
        }
    ]
}

Free License Usage

When you stop a Denodo server (e.g. Virtual DataPort server, Scheduler server, etc.), it sends an HTTP request to the License Manager, to notify that is going to stop. When the License Manager receives this request, it frees the corresponding license so it can be used by another server.

If a Denodo server stops working unexpectedly (e.g. the machine where it runs is restarted unexpectedly), you have to manually notify the License Manager that the license that this Denodo server was using, is no longer in use. Otherwise, the license will be considered in use until the grace period expires (5 days since the last time this Denodo server renewed its license).

To free up a license, log into the Solution Manager. In the Elements Tree, open the definition of the server whose license you want to free up and copy the field Host .

Then, send a request to this endpoint:

  • URL: /externalShutdown

  • Method: GET

  • URL parameters:

    • nodeIp: if the field Host in the Solution Manager is an IP address (not a host name), add this parameter to the URL.
    • hostDomainName: if the field Host in the Solution Manager is a host name, add this parameter to the URL.
    • port: port of the Denodo server.
    • product: identifier of the product. Currently, only VDP is supported.

Note

Only add the parameter nodeIp or hostDomainName to the URL, not both.

For example:

GET /externalShutdown?hostDomainName=denodo-dv1-prod.denodo.com&port=9999&product=VDP

The response body includes a summary of the operation with the result and a message:

{
    "result": ["OK" | "ERROR"],
    "message": <text>
}