API

Eine einfache Integration mit anderen Systemen ist uns sehr wichtig. Deswegen erklären wir Ihnen hier, wie Sie auf unsere API zugreifen können und welche Möglichkeiten Ihnen durch die API geboten werden. Die API wird mit folgender URL angesprochen:

https://api.enginsight.com

Authentifizierung

Die Authentifizierung mit der API wird über Access Keys (Zugriffsschlüssel) realisiert. Jeder Benutzer benötigt eigene Access Keys. Diese Access Keys bestehen aus einer Access Key ID und einem geheimen Access Key Secret. Um sich zu authentifizieren müssen Sie dieses Wertepaar in Ihren API Anfragen mit übergeben.

Beispiel-Anfrage: curl
$  curl --url https://api.enginsight.com/v1/endpoints \
    -H "x-ngs-access-key-id:     12345678910111213"   \
    -H "x-ngs-access-key-secret: abcdefghijklmnopq"
Die -H Option wird verwendet, um einen extra Header in einer HTTP-Anfrage an einen Server mitzugeben.
Es ist wichtig, dass der Access Key in einem Header übergeben wird.

Sie können Access Keys in Ihrem Account auf der Enginsight Plattform erstellen. Wie genau das geht, erfahren Sie im unteren Abschnitt. Mit den Access Keys erhält man viele Rechte, daher sollten sie sicher verwahrt werden. Sie können einen Access Key jederzeit löschen, dies ist allerdings ein endgültiger Vorgang, der nicht rückgängig gemacht werden kann. Sie können aber natürlich jederzeit einen neuen Access Key erstellen.

Einen neuen Access Key anlegen

Um einen neuen Access Key anzulegen gehen Sie in die Einstellungen unter Access Keys und klicken Sie auf Access Key erstellen.

Geben Sie dem Access Key eine treffende Beschreibung, z.B. Lokaler Observer und wählen Sie eine Umgebung aus. Klicken Sie abschließend auf Access Key erstellen.

Nun können Sie Ihren Access Key verwenden. In der Übersicht sehen Sie Ihre Beschreibung, die Rolle, die Access Key ID, das Access Key Secret, wann der Access Key zuletzt verwendet wurde und wann der Access Key erstellt wurde.

Über Secrets ein-/ ausblenden können Sie sich das geheime Access Key Secret anzeigen lassen. Wenn Sie auf das Mülltonnen-Symbol klicken, wird Ihr Access Key gelöscht.

Endpunkte

Einen neuen Endpunkt anlegen

Einen neuen Endpunkt können Sie folgendermaßen mit POST anlegen:

POST https://api.enginsight.com/v1/endpoints

Dabei müssen Sie Ihren Endpunkt als JSON-Objekt mit dem folgenden Grundgerüst mitschicken:

Endpunkt anlegen
  {
      "endpoint": {
          "target": "http://example.com",
          "description": "",
          "tags": [],
          "regions": ["eu-central-frankfurt", "us-east-virginia"],
          "observe": {
           "website": {
                  "enabled": true
           },
           "sslTls": {
                  "enabled": true
           },
           "httpHeaders": {
                "enabled": true
           },
           "wti": {
                 "enabled": true
           },
           "portScan": {
                 "enabled": true
           },
           "meta": {
                  "enabled": true
           }
          }
   }
  }
Feld Typ Beschreibung Beispiel
endpoint: Object Enthält alle Endpunktparameter.  
target String Geben Sie hier die URL des Endpunktes an. http://example.com
description String Geben Sie hier eine Beschreibung für den Endpunkt an. (optional) “Die schönste Beispielseite!”
tags Array Geben Sie hier Tags für den Endpunkt an. (optional) “beispiel”
regions Array Geben Sie hier die Regionen an, von denen aus der Endpunkt überwacht werden soll. Aktuell
können Sie wählen zwischen Frankfurt (eu-central-frankfurt) und Virginia (us-east-virginia).
“eu-central-frankfurt”

     
observe: Object Enthält die zu überwachenden Kategorien.  
website Object Die Einstellung “enabled”: true gibt an, dass Informationen aus der Kategorie “Webseite”
gesammelt und überwacht werden sollen.
 
sslTls Object Die Einstellung “enabled”: true gibt an, dass Informationen aus der Kategorie “SSL/TLS”
gesammelt und überwacht werden sollen.
 
httpHeaders Object Die Einstellung “enabled”: true gibt an, dass Informationen aus der Kategorie
“HTTP-Headers” gesammelt und überwacht werden sollen.
 
wti Object Die Einstellung “enabled”: true gibt an, dass Informationen aus der Kategorie
“Web Threat Intelligence” gesammelt und überwacht werden sollen.
 
portScan Object Die Einstellung “enabled”: true gibt an, dass Informationen aus der Kategorie “PortScan”
gesammelt und überwacht werden sollen.
 
meta Object Die Einstellung “enabled”: true bewirkt, dass die Beschreibung der Webseite automatisch
aus den Metadaten ermittelt wird, wenn das Feld “description” leer gelassen wird.
 

Achtung!

Die Response enthält die Endpunkt Id: “_id”. Das ist eine eindeutige Zeichenkette, die den Endpunkt identifiziert. Um Endpunkte über die API zu bearbeiten, wird diese Id zwingend benötigt.

Beispiel-Response
  {
      "endpoint": {
          "observe": {
              "meta": {
                  "interval": 86400,
                  "enabled": true
              },
              "website": {
                  "interval": 300,
                  "enabled": true
              },
              "sslTls": {
                  "interval": 3600,
                  "enabled": true
              },
              "httpHeaders": {
                  "interval": 3600,
                  "enabled": true
              },
              "redirects": {
                  "interval": 3600,
                  "enabled": false
              },
              "wti": {
                  "interval": 3600,
                  "enabled": true
              },
              "portScan": {
                  "interval": 3600,
                  "enabled": true
              },
          },
          "tags": [],
          "regions": ["eu-central-frankfurt", "us-east-virginia"],
          "_id": "123abc456def789ghi10",
          "target": "http://example.de",
          "description": "",
      }
  }

Alle Endpunkte aus Ihrer Umgebung auflisten

Sie können sich alle Endpunkte aus Ihrer Umgebung folgendermaßen mit GET auflisten lassen:

GET https://api.enginsight.com/v1/endpoints

Beispiel-Anfrage: curl

$  curl --url https://api.enginsight.com/v1/endpoints \
    -H "x-ngs-access-key-id:     12345678910111213"   \
    -H "x-ngs-access-key-secret: abcdefghijklmnopq"
Die -H Option wird verwendet, um einen extra Header in einer HTTP-Anfrage an einen Server mitzugeben.
Es ist wichtig, dass der Access Key in einem Header übergeben wird.

Das Ergebnis ist ein JSON-Objekt mit einer Auflistung aller Endpunkte.

Beispiel-Response
{
    "endpoints": [{
                "observe": {
                    "meta": {
                        "interval": 86400,
                        "enabled": true
                    },
                    "website": {
                        "interval": 300,
                        "enabled": false
                    },
                    "sslTls": {
                        "interval": 3600,
                        "enabled": true
                    },
                    "httpHeaders": {
                        "interval": 3600,
                        "enabled": true
                    },
                    "redirects": {
                        "interval": 3600,
                        "enabled": false
                    },
                    "wti": {
                        "interval": 3600,
                        "enabled": true
                    },
                    "portScan": {
                        "interval": 3600,
                        "enabled": true
                    },
                },
                "tags": [],
                "regions": [],
                "_id": "bei123spi456el7891011",
                "target": "https://example.com",
                "description": "",
            },
            {
                "observe": {
                    "meta": {
                        "interval": 86400,
                        "enabled": true
                    },
                    "website": {
                        "interval": 300,
                        "enabled": false
                    },
                    "sslTls": {
                        "interval": 3600,
                        "enabled": true
                    },
                    "httpHeaders": {
                        "interval": 3600,
                        "enabled": true
                    },
                    "redirects": {
                        "interval": 3600,
                        "enabled": false
                    },
                    "wti": {
                        "interval": 3600,
                        "enabled": true
                    },
                    "portScan": {
                        "interval": 3600,
                        "enabled": false
                    },
                },
                "tags": [],
                "regions": [],
                "_id": "123beispiel24567891011",
                "target": "https://example.org",
                "description": "",
            },
            {
                "...",
            },
    ]
}

Wofür die Informationen in den einzelnen Feldern stehen, können Sie den Tabellen aus dem Teil “Einen neuen Endpunkt anlegen” entnehmen.

Allgemeine Informationen über einen Endpunkt

Sie können sich allgemeine Informationen über einen bestimmten Endpunkt folgendermaßen mit GET anzeigen lassen:

GET https://api.enginsight.com/v1/endpoints/<endpointId>
  • Bitte setzen Sie anstatt des Platzhalters <endpointId> die Id des entsprechenden Endpunkts ein. Diese können Sie z.B. herausfinden, indem Sie sich alle Endpunkte aus Ihrer Umgebung auflisten lassen.
Beispiel-Anfrage: curl
$  curl --url https://api.enginsight.com/v1/123beispiel24567891011 \
    -H "x-ngs-access-key-id:     12345678910111213"                \
    -H "x-ngs-access-key-secret: abcdefghijklmnopq"
Die -H Option wird verwendet, um einen extra Header in einer HTTP-Anfrage an einen Server mitzugeben.
Es ist wichtig, dass der Access Key in einem Header übergeben wird.

Sie erhalten ein JSON-Objekt mit folgender Struktur zurück:

Ergebnisse
{
    "endpoint": {
        "screenshots": {
            "320x240": "https://example-screenshots.example.com/picture.jpg"
        },
        "observe": {
            "meta": {
                "interval": 86400,
                "enabled": true
            },
            "screenshot": {
                "interval": 86400,
                "enabled": true
            },
            "website": {
                "interval": 300,
                "enabled": true
            },
            "ping": {
                "interval": 300,
                "enabled": false
            },
            "sslTls": {
                "interval": 3600,
                "enabled": true
            },
            "httpHeaders": {
                "interval": 3600,
                "enabled": true
            },
            "redirects": {
                "interval": 300,
                "enabled": true
            },
            "wti": {
                "interval": 3600,
                "enabled": true
            },
            "portScan": {
                "interval": 3600,
                "enabled": true
            },
            "plugins": []
        },
        "dependencies": {
            "endpoints": []
        },
        "settings": {
            "summaries": {
                "enabled": false,
                "interval": 7
            }
        },
        "tags": [],
        "regions": [
            "eu-central-frankfurt"
        ],
        "variables": [],
        "_id": "123beispiel24567891011",
        "updatedAt": "2018-04-20T13:46:15.224Z",
        "createdAt": "2018-01-21T14:45:51.301Z",
        "organisation": "<organisationId>",
        "target": "https://test.example.com",
        "description": "",
        "__v": 0,
        "hostname": "test.example.com",
        "domain": "example.com",
        "id": "123beispiel24567891011"
    }
}

Wofür die Informationen in den einzelnen Feldern stehen, können Sie den Tabellen aus dem Teil “Einen neuen Endpunkt anlegen” entnehmen.

Verfügbarkeit eines Endpunkts

Die Verfügbarkeit bestimmten Endpunkts können Sie sich folgendermaßen mit GET anzeigen lassen:

GET https://api.enginsight.com/v1/endpoints/<endpointId>/observations/stats?horizont=<hours>&aggregate=<minutes>
  • Bitte setzen Sie anstatt des Platzhalters <endpointId> die Id des entsprechenden Endpunkts ein. Diese können Sie z.B. herausfinden, indem Sie sich alle Endpunkte aus Ihrer Umgebung auflisten lassen.
  • observations ist das Schlagwort für alle Funktionen, die mit dem Enginsight Modul Observer zusammenhängen. Nach dem ? sind die Parameter aufgelistet. Die Paramter werden durch das & Symbol getrennt. Lassen Sie den Wert für die obige Abfrage unverändert.
  • horizont=<hours> gibt an über welchen zurückliegenden Zeitraum die Verfügbarkeit des Endpunkts angezeigt wird, von jetzt bis - <hours> Stunden. horizont=168 würde z.B. die Verfügbarkeit des Endpunkts in den letzten 7 Tagen (168=7*24) anzeigen.
  • aggregate=<minutes> gibt an, wie viele Messungs-Intervalle zusammengefasst werden. Die Messung der Verfügbarkeit erfolgt immer alle 5 Minuten. Wenn Sie sich die Verfügbarkeit über einen langen Zeitraum wie z.B. mehrere Wochen anzeigen lassen wollen, kann das bei einem 5-Minuten Intervall zu langen Antwortszeiten führen. Deswegen können Sie mit dieser Variable steuern, wie viele 5 Minuten Intervalle zusammengefasst werden sollen. aggregate=15 bedeutet z.B. dass drei 5-Minuten Intervalle zu einem Wert zusammengefasst werden (nämlich dem Durchschnitt über die drei Intervalle).
Beispiel-Anfrage: curl
$  curl --url https://api.enginsight.com/v1/endpoints/123beispiel24567891011/observations/stats?horizont=168&aggregate=5 \
    -H "x-ngs-access-key-id:     12345678910111213"                                                                      \
    -H "x-ngs-access-key-secret: abcdefghijklmnopq"
Die -H Option wird verwendet, um einen extra Header in einer HTTP-Anfrage an einen Server mitzugeben.
Es ist wichtig, dass der Access Key in einem Header übergeben wird.

Das Ergebnis ist ein JSON Objekt mit folgender Struktur:

Beispiel-Response
{
    "stats": {
        "website": {
            "regions": {
                "eu-central-frankfurt": {
                    "availability": 100,
                }
            },
            "availability": 100
        }
    }
}
Feld Typ Beschreibung Beispiel
regions: Object Enthält die Regionen, von denen aus der Endpunkt beobachtet wird.  
{ eu-central-frankfurt Object Enthält die Regionspezifischen Statistiken, wie z.B. availability  
{ { availability Number Die Verfügbarkeit des Endpunktes, gemessen von der entsprechenden Region aus, in Prozent 100

     
availability Number Durchschnitt über die, von den entsprechenden Regionen gemessene, Verfügbarkeit des Endpunkts, in Prozent. 100

Zusammensetzung der Ladezeiten eines Endpunkts

Die Zusammensetzung der Ladezeiten eines bestimmten Endpunkts können Sie sich folgendermaßen mit GET anzeigen lassen:

GET https://api.enginsight.com/v1/endpoints/<endpointId>/observations?type=website&region=<region>&horizont=<hours>&aggregate=<minutes>
  • Bitte setzen Sie anstatt des Platzhalters <endpointId> die Id des entsprechenden Endpunkts ein. Diese können Sie z.B. herausfinden, indem Sie sich alle Endpunkte aus Ihrer Umgebung auflisten lassen.
  • observations ist das Schlagwort für alle Funktionen, die mit dem Enginsight Modul Observer zusammenhängen. Nach dem ? sind die Parameter aufgelistet. Die Paramter werden durch das & Symbol getrennt. Lassen Sie den Wert für die obige Abfrage unverändert.
  • type=website bestimmt, dass es sich um Daten aus der Überwachungskategorie “Website” handelt und nicht z.B. um Daten aus der Kategorie “SSL/TLS”. Lassen Sie den Wert für die obige Abfrage unverändert.
  • region=<region> gibt an, von wo aus der Endpunkt beobachtet wird. Bitte ersetzen Sie <region> durch den entsprechenden Wert z.B. “eu-central-frankfurt”. Auch diesen Wert können Sie aus der Auflistung der Endpunkte erhalten. Bitte beachten Sie, dass Sie zur Überprüfung der Zusammensetzung der Ladezeiten eines Endpunkts in der Abfrage nur eine Region angegeben können und nicht mehrere.
  • horizont=<hours> gibt an über welchen zurückliegenden Zeitraum die Zusammensetzung der Ladezeiten des Endpunkts angezeigt wird, von jetzt bis - <hours> Stunden. horizont=168 würde z.B. die Zusammensetzung der Ladezeiten des Endpunkts in den letzten 7 Tagen (168=7*24) anzeigen.
  • aggregate=<minutes> gibt an, wie viele Messungs-Intervalle zusammengefasst werden. Die Messung der Zusammensetzung der Ladezeiten erfolgt immer alle 5 Minuten. Wenn Sie sich die Zusammensetzung der Ladezeiten über einen langen Zeitraum wie z.B. mehrere Wochen anzeigen lassen wollen, kann das bei einem 5-Minuten Intervall zu langen Antwortszeiten führen. Deswegen können Sie mit dieser Variable steuern, wie viele 5 Minuten Intervalle zusammengefasst werden sollen. aggregate=15 bedeutet z.B. dass drei 5-Minuten Intervalle zu einem Wert zusammengefasst werden (nämlich dem Durchschnitt über die drei Intervalle).
Beispiel-Anfrage: curl
$  curl --url https://api.enginsight.com/v1/endpoints/123beispiel24567891011/observations?type=website&region=eu-central-frankfurt&horizont=168&aggregate=15 \
    -H "x-ngs-access-key-id:     12345678910111213"                                                                                                          \
    -H "x-ngs-access-key-secret: abcdefghijklmnopq"
Die -H Option wird verwendet, um einen extra Header in einer HTTP-Anfrage an einen Server mitzugeben.
Es ist wichtig, dass der Access Key in einem Header übergeben wird.

Das Ergebnis ist ein JSON Objekt mit folgender Struktur:

Beispiel-Response
{
    "observations": [{
                "_id": 1523885400000,
                "website": {
                    "dnsLookup": 0,
                    "connect": 5,
                    "preTransfer": 263,
                    "redirect": 263,
                    "startTransfer": 263,
                    "total": 295,
                }
            },
            {
                "_id": 1523886300000,
                "website": {
                    "dnsLookup": 0,
                    "connect": 5,
                    "preTransfer": 146,
                    "redirect": 146,
                    "startTransfer": 146,
                    "total": 162,
                }
            },
            {
                "...",
            },
    ]
}
Feld Typ Beschreibung Beispiel
_id Number Unix Time Stamp in Millisekunden 1523885400000 = Mon Apr 16 2018 10:30:00 GMT+0200 (Mitteleuropäische Sommerzeit)

PDF Reports

Einen PDF Report anlegen

Einen neuen PDF Report können Sie folgendermaßen mit POST anlegen:

POST https://api.enginsight.com/v1/endpoints/<endpointId>/summaries
  • Bitte setzen Sie anstatt des Platzhalters <endpointId> die Id des entsprechenden Endpunkts ein. Diese können Sie z.B. herausfinden, indem Sie sich alle Endpunkte aus Ihrer Umgebung auflisten lassen.
  • Das Anlegen des PDF Reports dauert ca. 5 Sekunden.
  • Status Code 200 und eine leere Response “[ ]” zeigen an, dass der PDF Report erfolgreich angelegt wurde.

Einen PDF Report downloaden

Zunächst stellen Sie folgende GET Anfrage:

GET https://api.enginsight.com/v1/endpoints/<endpointId>/summaries
  • Bitte setzen Sie anstatt des Platzhalters <endpointId> die Id des entsprechenden Endpunkts ein. Diese können Sie z.B. herausfinden, indem Sie sich alle Endpunkte aus Ihrer Umgebung auflisten lassen.
Beispiel-Anfrage: curl
$  curl --url https://api.enginsight.com/v1/endpoints/123beispiel24567891011/summaries \
    -H "x-ngs-access-key-id:     12345678910111213"                                    \
    -H "x-ngs-access-key-secret: abcdefghijklmnopq"
Die -H Option wird verwendet, um einen extra Header in einer HTTP-Anfrage an einen Server mitzugeben.
Es ist wichtig, dass der Access Key in einem Header übergeben wird.

Sie erhalten nun die Daten von allen, für diesen Endpunkt angelegten PDF Reports zurück. Diese können Sie nun beliebig sortieren, wenn Sie z.B. den neuesten PDF Report für den Endpunkt erhalten möchten, sortieren Sie einfach nach “createdAt”.

Ergebnisse
{
    "summaries": [{
            "createdAt": "2018-04-23T11:40:04.110Z",
            "_id": "report12345674950d2f05",
            "organisation": "596f52a3f372970001df4e77",
            "belongsTo": "endpoint",
        },
        {
            "createdAt": "2018-04-23T11:37:40.551Z",
            "_id": "report12345674950d2f05",
            "organisation": "596f52a3f372970001df4e77",
            "belongsTo": "endpoint",
        },
        {
            "...",
        },
    ]
}

Hier erhalten Sie nun auch sogenannten report IDs. Bitte wählen Sie die report Id des Entpunkts aus, dessen PDF Report Sie downloaden möchten und stellen Sie folgende GET Anfrage:

GET https://api.enginsight.com/v1/endpoints/summaries/<reportId>
Beispiel-Anfrage: curl
$  curl --url https://api.enginsight.com/v1/endpoints/summaries/report12345674950d2f05 \
    -H "x-ngs-access-key-id:     12345678910111213"                                    \
    -H "x-ngs-access-key-secret: abcdefghijklmnopq"
Die -H Option wird verwendet, um einen extra Header in einer HTTP-Anfrage an einen Server mitzugeben.
Es ist wichtig, dass der Access Key in einem Header übergeben wird.

Nun sollte Ihnen der PDF Bericht zur Verfügung stehen.