Skip to main content

Reports

API Calls​

NameDescriptionShortcut
GET: List reports or single reportThis method can be used to retrieve a list of existing reports Description
POST: Create a new reportThis method can be used to create a new report. Description
PUT: Update an existing reportThis method can be used to update an existing report. Description
DELETE: Delete an existing ReportThis method can be used to delete an existing report. Description

[GET]: List Reports​

This method can be used to retrieve a list of existing reports or a single report according to its ID.

Input​

URL​

/reports
or
/reports/{id}

Request headers​

x-api-key: shared_key_value
Accept: application/json

Response​

Headers: Status: 200 OK

Response body​

Json Response

{
    "status": {
        "message": "Success",
        "code": "200"
    },
    "data": [
        {
            "id": "eba61a9e-22e9-4521-9e47-ecaa4a494364",
            "tenant": "TenantA",
            "disabled": false,
            "info": {
                "name": "Report_A",
                "description": "report aaaaa",
                "created": "2015-9-10 13:43:00",
                "updated": "2015-10-11 13:43:00"
            },
            "computations": {
                "ar": true,
                "status": true,
                "trends": [
                              "flapping",
                              "status",
                              "tags"
                          ]
            },
            "topology_schema": {
                "group": {
                    "type": "NGI",
                    "group": {
                        "type": "SITE"
                    }
                }
            },
            "thresholds": {
                "availability": 80.0,
                "reliability": 85.0,
                "uptime": 80.0,
                "unknown": 10.0,
                "downtime": 10.0
            },
            "profiles": [
                {
                    "id": "6ac7d684-1f8e-4a02-a502-720e8f11e50b",
                    "name": "profile1",
                    "type": "metric"
                },
                {
                    "id": "6ac7d684-1f8e-4a02-a502-720e8f11e523",
                    "name": "profile2",
                    "type": "operations"
                },
                {
                    "id": "6ac7d684-1f8e-4a02-a502-720e8f11e50q",
                    "name": "profile3",
                    "type": "aggregation"
                }
            ],
            "filter_tags": [
                {
                    "name": "name1",
                    "value": "value1",
                    "context": ""
                },
                {
                    "name": "name2",
                    "value": "value2",
                    "context": ""
                }
            ]
        }
    ]
}

[POST]: Create a new report​

This method can be used to create a new report

Input​

URL​

POST /reports

Request headers​

x-api-key: shared_key_value
Accept: application/json

Request Body​

{
    "info": {
        "name": "Report_A",
        "description": "report aaaaa"
    },
    "topology_schema": {
        "group": {
            "type": "ngi",
            "group": {
                "type": "site"
            }
        }
    },
    "computations": {
        "ar": true,
        "status": true,
        "trends": [
                        "flapping",
                        "status",
                        "tags"
                    ]
    },
    "thresholds": {
        "availability": 80.0,
        "reliability": 85.0,
        "uptime": 80.0,
        "unknown": 10.0,
        "downtime": 10.0
    },
    "profiles": [
        {
            "id": "422985a7-6386-4964-bc99-5ebd5d7b0aef",
            "type": "metric"
        },
        {
            "id": "1aa74849-2310-4bbc-b63a-8995ac7888ea",
            "type": "aggregation"
        },
        {
            "id": "1eafbdd1-1bbc-4861-b849-65394840762",
            "type": "operations"
        }
    ],
    "filter_tags": [
        {
            "name": "production",
            "value": "N"
        },
        {
            "name": "monitored",
            "value": "Y"
        }
    ]
}

Response​

Headers: Status: 201 Created

Response Body​

{
    "status": {
        "message": "Successfully Created Report",
        "code": "201"
    },
    "data": {
        "id": "eba61a9e-22e9-4521-9e47-ecaa4a494360",
        "links": {
            "self": "https://myapi.test.com/api/v2/reports/eba61a9e-22e9-4521-9e47-ecaa4a494360"
        }
    }
}

[PUT]: Update an existing report​

This method can be used to update an existing report. This will replace all the fields in the record so all the old fields that need to be kept must be included in the json of the update request body

Input​

URL​

/reports/{id}

Request headers​

x-api-key: shared_key_value
Accept: application/json

Request Body​

{
    "disabled": true,
    "weight": "hepspec",
    "info": {
        "name": "newname",
        "description": "newdescription"
    },
    
    "topology_schema": {
        "group": {
            "type": "ngi",
            "group": {
                "type": "fight"
            }
        }
    },
    "thresholds": {
        "availability": 90.0,
        "reliability": 95.0,
        "uptime": 90.0,
        "unknown": 15.0,
        "downtime": 15.0
    },
    "profiles": [
        {
            "id": "6ac7d684-1f8e-4a02-a502-720e8f11e50b",
            "type": "metric",
            "name": "profile1"
        },
        {
            "id": "6ac7d684-1f8e-4a02-a502-720e8f11e523",
            "type": "operations",
            "name": "profile2"
        },
        {
            "id": "6ac7d684-1f8e-4a02-a502-720e8f11e50bq",
            "type": "aggregation",
            "name": "profile3"
        }
    ],
    "filter_tags": [
        {
            "name": "production",
            "value": "N"
        },
        {
            "name": "monitored",
            "value": "N"
        }
    ]
}

Response​

Headers: Status: 200 OK

Response Body​

{
    "status": {
        "message": "Report was successfully updated",
        "code": "200"
    }
}

[DELETE]: Delete an existing report​

This method can be used to update an existing report

Input​

URL​

DELETE /reports/{id}

Request headers​

x-api-key: shared_key_value
Accept: application/json

Response​

Headers: Status: 200 OK

Response Body​

{
    "status": {
        "message": "Report was successfully deleted",
        "code": "200"
    }
}

Notes on Report Filter tags and topology​

As we seen before a report can host a list of filter tags using the following list under the filed filter_tags:

{
    "filter_tags": [
        {
            "context": "a context description to define where the filter applies",
            "name": "what to be filter",
            "value": "filter pattern described here"
        }
    ]
}

There are special argo contexts that are automatically picked up to filter group and endpoint topology. These contexts are described below:

  • context: argo.group.filter.fields - Used to apply filter on basic fields of group topology. Under this context the name targets the group field name and the value holds the actual field pattern
  • context: argo.group.filter.tags - Used to apply filter on tags of group topology. Under this context the name targets the group tag name and the value holds the actual field pattern
  • context: argo.group.filter.tags.array - Used to apply filter, containing a list of comma separated values, on tags of group topology. Under this context the name targets the group tag name and the value holds the actual field pattern
  • context: argo.endpoint.filter.fields - Used to apply filter on basic fields of endpoint topology. Under this context the name targets the endpoint field name and the value holds the actual field pattern
  • context: argo.endpoint.filter.tags - Used to apply filter on tags of endpoint topology. Under this context the name targets the endpoint tag name and the value holds the actual field pattern
  • context: argo.endpoint.filter.tags.array - Used to apply filter, containing a list of comma separated values, on tags of endpoint topology. Under this context the name targets the endpoint tag name and the value holds the actual field pattern

note : You can use ~ as a negative operator in the beginning of a filter value to exclude something: For example you can exclude endpoints with service of value SERVICE_A by issuing the following filter tag in the report:

{
    "context": "argo.endpoint.filter.fields",
    "name": "service",
    "value": "~SERVICE_A"
}

Notes on Optional profile references​

In the report's profiles list of references, along with the mandatory metric, operations and aggregation profiles, the user can declare references to the optionally used thresholds and weights profiles. User of the report must ensure that the declared reference ids are legit for each corresponding profile type.

Example of report with all profile type references declared:

{
    "status": {
        "message": "Success",
        "code": "200"
    },
    "data": [
        {
            "id": "eba61a9e-22e9-4521-9e47-ecaa4a494364",
            "tenant": "TenantA",
            "disabled": false,
            "info": {
                "name": "Report_A",
                "description": "report aaaaa",
                "created": "2015-9-10 13:43:00",
                "updated": "2015-10-11 13:43:00"
            },
            "topology_schema": {
                "group": {
                    "type": "NGI",
                    "group": {
                        "type": "SITE"
                    }
                }
            },
            "thresholds": {
                "availability": 80.0,
                "reliability": 85.0,
                "uptime": 80.0,
                "unknown": 10.0,
                "downtime": 10.0
            },
            "profiles": [
                {
                    "id": "6ac7d684-1f8e-4a02-a502-720e8f11e50b",
                    "name": "profile1",
                    "type": "metric"
                },
                {
                    "id": "6ac7d684-1f8e-4a02-a502-720e8f11e523",
                    "name": "profile2",
                    "type": "operations"
                },
                {
                    "id": "6ac7d684-1f8e-4a02-a502-720e8f11e50q",
                    "name": "profile3",
                    "type": "aggregation"
                },
                {
                    "id": "vac7d684-1f8e-4a02-a502-720e8f11e555",
                    "name": "profile_38393",
                    "type": "thresholds"
                },
                {
                    "id": "rac65684-ff8e-5a02-6502-720e8f11e50q",
                    "name": "profile_393",
                    "type": "weights"
                }
            ],
            "filter_tags": [
                {
                    "name": "name1",
                    "value": "value1",
                    "context": ""
                },
                {
                    "name": "name2",
                    "value": "value2",
                    "context": ""
                }
            ]
        }
    ]
}

During report creation, in case of wrong profile type reference defined or wrong profile uuid the following type of error will occur as a response:

{
    "status": {
        "message": "Unprocessable Entity",
        "code": "422"
    },
    "errors": [
        {
            "message": "Profile id not found",
            "code": "422",
            "details": "No profile in operations_profiles was found with id 93930-wrong-id"
        },
        {
            "message": "Profile type invalid",
            "code": "422",
            "details": "Profile type whatever_profile is invalid"
        }
    ]
}

Notes on Computations field​

Computations field is used per report to define what kind of computations should run per report execution. Each report can produce availability/reliability (ar) results, status timelines and specific trends such as top flapping items, top items in status Critical,Warning etc.. and also top issues reported by tags. User can specify exactly what needs to be computed when a report runs by using the special computations field and define the following:

{
    "computations": {
        "ar": true,
        "status": true,
        "trends": [
                        "flapping",
                        "status",
                        "tags"
                    ]
    }
}

This information is automatically picked up by the analytics engine and the specified computation are executed. When creating or updating a report the computations field is optional. If the User omits it then the default value will include that everything should be computed.