Discovery API

The Discovery endpoint (GET /) provides a machine-readable list of Clumio REST API resources. The response includes a list of resources and within each of the resources, the associated operation IDs. Each set of resources is organized by release version, starting with the earliest available version.

In the following example, the consolidated-alerts resource includes a list of operation IDs. Operation ID list-consolidated-alerts was released in v1. With the v2 release three operation IDs were released: a newer version of list-consolidated-alerts, and two new ones read-consolidated-alerts, and update-consolidated-alerts.

{
    "consolidated-alerts": {
        "supported_versions": [
            "v2", "v1"
        ],
        "v1": {
            "list-consolidated-alerts": {
                "href": "/alerts/consolidated",
                "type": "get",
                "templated": false
            }
        },
        "v2": {
            "list-consolidated-alerts": {
                "href": "/alerts/consolidated",
                "type": "get",
                "templated": false
            },
            "read-consolidated-alert": {
                "href": "/alerts/consolidated/{consolidated_alert_id}",
                "type": "get",
                "templated": true
            },
            "update-consolidated-alert": {
                "href": "/alerts/consolidated/{consolidated_alert_id}",
                "type": "patch",
                "templated": true
            }
        }
    }
}

To protect clients from encountering broken links due to server-side URL changes, when referring to a resource location (URL) within a script, use the resource name and operation ID to retrieve the URL rather than by hard-coding the URL itself. For example, to list consolidated alerts, use the resource name consolidated-alerts and its operation ID list-consolidated-alerts.

To avoid network calls at each request, cache the Discovery REST API response.

In addition to displaying a list of Clumio REST API resources, the Discovery API response also contains the version string of the current release in the Content-Type HTTP response header. For example:

Content-Type: application/api.clumio.\*=v1+json

The version string must be included in the header of every request to specify the version used at the resource level.

See Versioning for more information.