Version

    Chapter 43. REST API

    Overview

    The CloverDX REST API enables you to interact with CloverDX Server programmatically. You can use it to script interactions or develop various kinds of integrations with the Server. The API provides access to CloverDX Server resources by using a predefined set of stateless operations realized via HTTP calls. Requests to resource URIs, and also the received responses, use a payload formatted in JSON. The REST API uses the standard HTTP status codes.

    The Server also provides a generated REST API documentation available at

    http://[domain]:[port]/clover/api/rest/[api-version]/docs.html

    for example:

    http://example.com:8080/clover/api/rest/v1/docs.html

    and it should be the main source of information for using the API.

    Version and URI

    This documentation is for version 1 of the REST API, which is the latest version. The URIs for resources have the following structure:

    http://[domain]:[port]/clover/api/rest/v1/[resource-path]

    for example:

    http://example.com:8080/clover/api/rest/v1/dashboards/1/monitors

    Authentication and Authorization

    Requests to the API must be authenticated, the API uses basic HTTP authentication. Regarding authorization, the user used to authenticate the request needs to have the required permissions to read or modify the specific resource.

    All operations on monitors require the existing permission Monitoring section.

    CSRF Protection

    The REST API provides protection against Cross-Site Request Forgery (CSRF) attacks. The mechanism basically requires the presence of a X-Requested-By header in every request to the API, same as described in chapter Simple HTTP API, in the section called “CSRF Protection” and is also controlled globally by the same configuration property security.csrf.protection.enabled.

    To put all the information together, an example API request to create a new monitor resource can look like:

    curl -X POST "http://example.com:8080/clover/api/rest/v1/dashboards/1/monitors" -H "Accept: application/json" -H "Content-Type: application/json" -H "X-Requested-By: arbitrary_value" -u username:password -d "@request.json"

    where username:password are the user's credentials and request.json is a file containing the request body.

    Resources and Operations

    Below is a list of resources and operations (URI paths and HTTP methods) available in the API and examples of request and/or response bodies.

    In the examples, you may notice that every resource has a special property @self. This URI is a unique identifier of a resource in the API. These URIs can be used to traverse the API and discover other related resources, which is one of the principles of a REST API called Hypermedia as the engine of application state (HATEOAS).

    [Note]Note
    The examples use the sandbox DWHExample and resources from it. It can be deployed while completing the Server Console tutorial. Also note that most of the resources are identified by numerical IDs, which will be different in your use case.

    Dashboards

    Dashboard represents a group of monitors.

    See also Operations Dashboard.

    GET /dashboards

    Returns a list of all existing dashboards.

    Example 43.1. Request

    curl -X GET "http://example.com:8080/clover/api/rest/v1/dashboards" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.2. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/dashboards",
        "@type": "DashboardCollection",
        "@totalItems": 1,
        "members": [
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/dashboards/1",
                "@type": "Dashboard",
                "name": "CloverDX Operations Dashboard",
                "monitors": [
                    {
                        "@self": "http://example.com:8080/clover/api/rest/v1/dashboards/1/monitors/191",
                        "@type": "Monitor",
                        "name": "DWHExampleMonitor",
                        "status": {
                            "status": "OK",
                            "passing": 2,
                            "failing": 0
                        }
                    }
                ]
            }
        ]
    }


    GET /dashboards/{dashboardId}

    Returns the details for a dashboard. The dashboard is identified by its ID. The response contains a list of existing monitors which belong to the dashboard and their status. Further information about a specific monitor can be obtained with a new request to the monitors endpoint.

    Example 43.3. Request

    curl -X GET "http://example.com:8080/clover/api/rest/v1/dashboards/1" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.4. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/dashboards/1",
        "@type": "Dashboard",
        "name": "CloverDX Operations Dashboard",
        "monitors": [
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/dashboards/1/monitors/191",
                "@type": "Monitor",
                "name": "DWHExampleMonitor",
                "status": {
                    "status": "OK",
                    "passing": 2,
                    "failing": 0
                }
            }
        ]
    }


    Monitors

    Monitor represents a state of a business process, a cumulative state of multiple monitorable items (schedules, event listeners or data services).

    See also Operations Dashboard.

    GET /dashboards/{dashboardId}/monitors

    Returns a list of all monitors in a dashboard, identified by dashboard ID.

    Example 43.5. Request

    curl -X GET "http://example.com:8080/clover/api/rest/v1/dashboards/1/monitors" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.6. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/dashboards/1/monitors",
        "@type": "MonitorCollection",
        "@totalItems": 1,
        "members": [
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/dashboards/1/monitors/191",
                "@type": "Monitor",
                "name": "DWHExampleMonitor",
                "status": {
                    "status": "OK",
                    "passing": 2,
                    "failing": 0
                },
                "items": [
                    {
                        "@self": "http://example.com:8080/clover/api/rest/v1/schedules/74",
                        "@type": "Schedule",
                        "name": "DWHExample Sample Data Generator",
                        "status": {
                            "status": "OK",
                            "@links": {
                                "reset": "http://example.com:8080/clover/api/rest/v1/schedules/74/reset-status"
                            }
                        }
                    },
                    {
                        "@self": "http://example.com:8080/clover/api/rest/v1/listeners/69",
                        "@type": "Listener",
                        "name": "DWHExample Input file listener",
                        "status": {
                            "status": "OK",
                            "@links": {
                                "reset": "http://example.com:8080/clover/api/rest/v1/listeners/69/reset-status"
                            }
                        }
                    }
                ]
            }
        ]
    }


    POST /dashboards/{dashboardId}/monitors

    Creates a new monitor from the definition in request body and returns the created monitor's new representation.

    Example 43.7. Request

    curl -X POST "http://example.com:8080/clover/api/rest/v1/dashboards/1/monitors" -H "Accept: application/json" -H "Content-Type: application/json" -H "X-Requested-By: api-examples" -u username:password -d "@request.json"


    Example 43.8. Request Body (request.json)

    {
        "name": "DWHExampleMonitor",
        "items": [
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/schedules/74",
                "@type": "Schedule"
            },
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/listeners/69",
                "@type": "Listener"
            }
        ]
    }


    Example 43.9. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/dashboards/1/monitors/191",
        "@type": "Monitor",
        "name": "DWHExampleMonitor",
        "status": {
            "status": "OK",
            "passing": 2,
            "failing": 0
        },
        "items": [
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/schedules/74",
                "@type": "Schedule",
                "name": "DWHExample Sample Data Generator",
                "status": {
                    "status": "OK",
                    "@links": {
                        "reset": "http://example.com:8080/clover/api/rest/v1/schedules/74/reset-status"
                    }
                }
            },
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/listeners/69",
                "@type": "Listener",
                "name": "DWHExample Input file listener",
                "status": {
                    "status": "OK",
                    "@links": {
                        "reset": "http://example.com:8080/clover/api/rest/v1/listeners/69/reset-status"
                    }
                }
            }
        ]
    }


    GET /dashboards/{dashboardId}/monitors/{monitorId}

    Returns the details for a monitor. The monitor is identified by its ID. The response contains the details of a monitor, including its name, status, number of OK and failing items, and a list of the individual monitored items.

    Example 43.10. Request

    curl -X GET "http://example.com:8080/clover/api/rest/v1/dashboards/1/monitors/191" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.11. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/dashboards/1/monitors/191",
        "@type": "Monitor",
        "name": "DWHExampleMonitor",
        "status": {
            "status": "OK",
            "passing": 2,
            "failing": 0
        },
        "items": [
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/schedules/74",
                "@type": "Schedule",
                "name": "DWHExample Sample Data Generator",
                "status": {
                    "status": "OK",
                    "@links": {
                        "reset": "http://example.com:8080/clover/api/rest/v1/schedules/74/reset-status"
                    }
                }
            },
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/listeners/69",
                "@type": "Listener",
                "name": "DWHExample Input file listener",
                "status": {
                    "status": "OK",
                    "@links": {
                        "reset": "http://example.com:8080/clover/api/rest/v1/listeners/69/reset-status"
                    }
                }
            }
        ]
    }


    PUT /dashboards/{dashboardId}/monitors/{monitorId}

    Updates an existing monitor, identified by an ID, from the definition in request body and returns the updated monitor's new representation.

    Example 43.12. Request

    curl -X PUT "http://example.com:8080/clover/api/rest/v1/dashboards/1/monitors/191" -H "Accept: application/json" -H "Content-Type: application/json" -H "X-Requested-By: api-examples" -u username:password -d "@request.json"


    Example 43.13. Request Body (request.json)

    {
        "name": "DWHExampleMonitor",
        "items": [
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/schedules/74",
                "@type": "Schedule"
            },
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/data-services/91",
                "@type": "DataService"
            }
        ]
    }


    Example 43.14. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/dashboards/1/monitors/191",
        "@type": "Monitor",
        "name": "DWHExampleMonitor",
        "status": {
            "status": "OK",
            "passing": 2,
            "failing": 0
        },
        "items": [
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/schedules/74",
                "@type": "Schedule",
                "name": "DWHExample Sample Data Generator",
                "status": {
                    "status": "OK",
                    "@links": {
                        "reset": "http://example.com:8080/clover/api/rest/v1/schedules/74/reset-status"
                    }
                }
            },
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/data-services/91",
                "@type": "DataService",
                "name": "ReportMonthlySummary",
                "status": {
                    "status": "OK",
                    "@links": {
                        "reset": "http://example.com:8080/clover/api/rest/v1/data-services/91/reset-status"
                    }
                }
            }
        ]
    }


    DELETE /dashboards/{dashboardId}/monitors/{monitorId}

    Deletes an existing monitor. The monitor is identified by its ID.

    Example 43.15. Request

    curl -X DELETE "http://example.com:8080/clover/api/rest/v1/dashboards/1/monitors/191" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Schedules

    The REST API resource for a schedule is not a full representation of a schedule (as seen in Server Console). It contains only a bare minimum required for state monitoring, which also means that only a read access is available (GET method).

    See also Scheduling.

    GET /schedules

    Returns a list of all existing schedules.

    Example 43.16. Request

    curl -X GET "http://example.com:8080/clover/api/rest/v1/schedules" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.17. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/schedules",
        "@type": "ScheduleCollection",
        "@totalItems": 1,
        "members": [
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/schedules/74",
                "@type": "Schedule",
                "name": "DWHExample Sample Data Generator",
                "status": {
                    "status": "OK",
                    "@links": {
                        "reset": "http://example.com:8080/clover/api/rest/v1/schedules/74/reset-status"
                    }
                },
                "relatedSandbox": {
                    "@self": "http://example.com:8080/clover/api/rest/v1/sandboxes/DWHExample",
                    "@type": "Sandbox",
                    "name": "DWHExample",
                    "code": "DWHExample"
                },
                "triggerDescription": "Every 5 minutes"
            }
        ]
    }


    GET /schedules/{scheduleId}

    Returns the details for a schedule. The schedule is identified by its ID. The response contains the details of a schedule as a monitorable item, including its name, status, link to reset the status, trigger description and a sandbox, if the schedule belongs to a sandbox.

    Example 43.18. Request

    curl -X GET "http://example.com:8080/clover/api/rest/v1/schedules/74" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.19. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/schedules/74",
        "@type": "Schedule",
        "name": "DWHExample Sample Data Generator",
        "status": {
            "status": "FAIL",
            "errorMessage": "execute_jobflow: DWHExample/jobflow/data-generator/DWHExampleScheduledGenerator.jbf executed with status ERROR, with error: Component [Fail:FAIL] finished with status ERROR. (In0: 1 recs)\n Blocked by another process (lockfile ./data-tmp/.lock_scheduled...",
            "failingSince": "2020-10-01T10:10:58.026+02:00",
            "failureCount": 1,
            "@links": {
                "reset": "http://example.com:8080/clover/api/rest/v1/schedules/74/reset-status"
            }
        },
        "relatedSandbox": {
            "@self": "http://example.com:8080/clover/api/rest/v1/sandboxes/DWHExample",
            "@type": "Sandbox",
            "name": "DWHExample",
            "code": "DWHExample"
        },
        "triggerDescription": "Every 5 minutes"
    }


    POST /schedules/{scheduleId}/reset-status

    Resets a schedule's status to OK and returns the schedule's new representation. Schedule status refers to an OK or failing state as described in Alerts and Notification.

    Example 43.20. Request

    curl -X POST "http://example.com:8080/clover/api/rest/v1/schedules/74/reset-status" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.21. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/schedules/74",
        "@type": "Schedule",
        "name": "DWHExample Sample Data Generator",
        "status": {
            "status": "OK",
            "@links": {
                "reset": "http://example.com:8080/clover/api/rest/v1/schedules/74/reset-status"
            }
        },
        "relatedSandbox": {
            "@self": "http://example.com:8080/clover/api/rest/v1/sandboxes/DWHExample",
            "@type": "Sandbox",
            "name": "DWHExample",
            "code": "DWHExample"
        },
        "triggerDescription": "Every 5 minutes"
    }


    Listeners

    The REST API resource for a listener is not a full representation of a listener (as seen in Server Console). It contains only a bare minimum required for state monitoring, which also means that only a read access is available (GET method).

    See also Listeners.

    GET /listeners

    Returns a list of all existing listeners.

    Example 43.22. Request

    curl -X GET "http://example.com:8080/clover/api/rest/v1/listeners" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.23. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/listeners",
        "@type": "ListenerCollection",
        "@totalItems": 1,
        "members": [
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/listeners/69",
                "@type": "Listener",
                "name": "DWHExample Input file listener",
                "status": {
                    "status": "OK",
                    "@links": {
                        "reset": "http://example.com:8080/clover/api/rest/v1/listeners/69/reset-status"
                    }
                },
                "relatedSandbox": {
                    "@self": "http://example.com:8080/clover/api/rest/v1/sandboxes/DWHExample",
                    "@type": "Sandbox",
                    "name": "DWHExample",
                    "code": "DWHExample"
                },
                "triggerDescription": "On file DWHExample* added at ${sandboxes.home}/DWHExample/data-in/input/"
            }
        ]
    }


    GET /listeners/{listenerId}

    Returns the details for a listener. The listener is identified by its ID. The response contains the details of a listener as a monitorable item, including its name, status, link to reset the status, trigger description and a sandbox, if the listener belongs to a sandbox.

    Example 43.24. Request

    curl -X GET "http://example.com:8080/clover/api/rest/v1/listeners/69" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.25. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/listeners/69",
        "@type": "Listener",
        "name": "DWHExample Input file listener",
        "status": {
            "status": "OK",
            "@links": {
                "reset": "http://example.com:8080/clover/api/rest/v1/listeners/69/reset-status"
            }
        },
        "relatedSandbox": {
            "@self": "http://example.com:8080/clover/api/rest/v1/sandboxes/DWHExample",
            "@type": "Sandbox",
            "name": "DWHExample",
            "code": "DWHExample"
        },
        "triggerDescription": "On file DWHExample* added at ${sandboxes.home}/DWHExample/data-in/input/"
    }


    POST /listeners/{listenerId}/reset-status

    Resets a listener's status to OK and returns the listener's new representation. Listener status refers to an OK or failing state as described in Alerts and Notification.

    Example 43.26. Request

    curl -X POST "http://example.com:8080/clover/api/rest/v1/listeners/69/reset-status" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.27. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/listeners/69",
        "@type": "Listener",
        "name": "DWHExample Input file listener",
        "status": {
            "status": "OK",
            "@links": {
                "reset": "http://example.com:8080/clover/api/rest/v1/listeners/69/reset-status"
            }
        },
        "relatedSandbox": {
            "@self": "http://example.com:8080/clover/api/rest/v1/sandboxes/DWHExample",
            "@type": "Sandbox",
            "name": "DWHExample",
            "code": "DWHExample"
        },
        "triggerDescription": "On file DWHExample* added at ${sandboxes.home}/DWHExample/data-in/input/"
    }


    Data Services

    The REST API resource for a data service is not a full representation of a data service (as seen in Server Console). It contains only a bare minimum required for state monitoring, which also means that only a read access is available (GET method).

    See also Data Services.

    GET /data-services

    Returns a list of all existing data services.

    Example 43.28. Request

    curl -X GET "http://example.com:8080/clover/api/rest/v1/data-services" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.29. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/data-services",
        "@type": "DataServiceCollection",
        "@totalItems": 1,
        "members": [
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/data-services/91",
                "@type": "DataService",
                "name": "ReportMonthlySummary",
                "status": {
                    "status": "OK",
                    "@links": {
                        "reset": "http://example.com:8080/clover/api/rest/v1/data-services/91/reset-status"
                    }
                },
                "relatedSandbox": {
                    "@self": "http://example.com:8080/clover/api/rest/v1/sandboxes/DWHExample",
                    "@type": "Sandbox",
                    "name": "DWHExample",
                    "code": "DWHExample"
                },
                "triggerDescription": "On request to endpoint"
            }
        ]
    }


    GET /data-services/{dataServiceId}

    Returns the details for a data service. The data service is identified by its ID. The response contains the details of a data service as a monitorable item, including its name, status, link to reset the status, trigger description and a sandbox, if the data service belongs to a sandbox.

    Example 43.30. Request

    curl -X GET "http://example.com:8080/clover/api/rest/v1/data-services/91" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.31. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/data-services/91",
        "@type": "DataService",
        "name": "ReportMonthlySummary",
        "status": {
            "status": "OK",
            "@links": {
                "reset": "http://example.com:8080/clover/api/rest/v1/data-services/91/reset-status"
            }
        },
        "relatedSandbox": {
            "@self": "http://example.com:8080/clover/api/rest/v1/sandboxes/DWHExample",
            "@type": "Sandbox",
            "name": "DWHExample",
            "code": "DWHExample"
        },
        "triggerDescription": "On request to endpoint"
    }


    POST /data-services/{dataServiceId}/reset-status

    Resets a data service's status to OK and returns the data service's new representation. Data service status refers to an OK or failing state as described in Alerts and Notification.

    Example 43.32. Request

    curl -X POST "http://example.com:8080/clover/api/rest/v1/data-services/91/reset-status" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.33. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/data-services/91",
        "@type": "DataService",
        "name": "ReportMonthlySummary",
        "status": {
            "status": "OK",
            "@links": {
                "reset": "http://example.com:8080/clover/api/rest/v1/data-services/91/reset-status"
            }
        },
        "relatedSandbox": {
            "@self": "http://example.com:8080/clover/api/rest/v1/sandboxes/DWHExample",
            "@type": "Sandbox",
            "name": "DWHExample",
            "code": "DWHExample"
        },
        "triggerDescription": "On request to endpoint"
    }


    Sandboxes

    The REST API resource for a sandbox is not a full representation of a sandbox (as seen in Server Console). It contains only a bare minimum required for state monitoring, which also means that only a read access is available (GET method).

    See also Sandboxes.

    GET /sandboxes

    Returns a list of all existing sandboxes.

    Example 43.34. Request

    curl -X GET "http://example.com:8080/clover/api/rest/v1/sandboxes" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.35. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/sandboxes",
        "@type": "SandboxCollection",
        "@totalItems": 1,
        "members": [
            {
                "@self": "http://example.com:8080/clover/api/rest/v1/sandboxes/DWHExample",
                "@type": "Sandbox",
                "name": "DWHExample",
                "code": "DWHExample"
            }
        ]
    }


    GET /sandboxes/{sandboxCode}

    Returns the details for a sandbox. The sandbox is identified by its sandbox code. The response contains the sandbox name and sandbox code.

    Example 43.36. Request

    curl -X GET "http://example.com:8080/clover/api/rest/v1/sandboxes/DWHExample" -H "Accept: application/json" -H "X-Requested-By: api-examples" -u username:password


    Example 43.37. Response Body

    {
        "@self": "http://example.com:8080/clover/api/rest/v1/sandboxes/DWHExample",
        "@type": "Sandbox",
        "name": "DWHExample",
        "code": "DWHExample"
    }