content-sync KNW-1797 pick-25 translation finished, ticket done

Author: eseyffarth

src/common/de/rest_api.asciidoc

@@ -12,7 +12,7 @@ include::global_attr.adoc[]
 
 Mit der {CMK} REST-API als Anwendungsprogrammierschnittstelle können Sie die Aufgaben, die Sie sonst in {CMK} über die GUI erledigen, per Kommando oder Skript mit HTTP-Anfragen an den {CMK}-Server übermitteln und ausführen lassen.
 
-Das _REST_ im Namen der REST-API steht für _REpresentational State Transfer_ und beschreibt eine Architektur für den Austausch von Daten auf verteilten Systemen -- insbesondere für Web-Dienste.
+Das _REST_ im Begriff _REST-API_ steht für _REpresentational State Transfer_ und beschreibt eine Architektur für den Austausch von Daten auf verteilten Systemen -- insbesondere für Web-Dienste.
 Eine API, die gemäß der REST-Architektur implementiert ist, folgt bestimmten Prinzipien, z.B. dem Client-Server-Modell, der zustandslosen Kommunikation und einer einheitlichen Schnittstelle.
 In der Praxis erfolgt die Umsetzung bevorzugt über das HTTP-Protokoll, wobei die Ressourcen per Uniform Resource Identifier (URI) angesprochen werden und auf diese mit HTTP-Methoden (GET, POST, PUT, DELETE) zugegriffen wird.
 
@@ -62,7 +62,7 @@ stattdessen finden Sie die API-Dokumentation außerhalb dieses Handbuchs, direkt
 Die API mit ihrer Dokumentation ist versioniert.
 ifdef::onprem[]
 Seit {CMK} {v25} wird die REST-API in der Version `v1` mit der {CMK}-Software zusammen ausgeliefert.
-Diese Version der API ist kompatibel mit der Version `1.0`, die bis {CMK} {v24} zur Verfügung gestellt wurde.
+Diese Version der API ist kompatibel mit der Version `1.0`, die bis {CMK} {v24} zur Verfügung gestellt wird.
 endif::[]
 ifdef::saas[]
 Sie ist aktuell in der Version `v1` in {CE} enthalten.
@@ -88,7 +88,7 @@ Erst mit der nächsten Major-Version von {CMK} werden abgekündigte API-Versione
 endif::[]
 So liegt es in Ihrer Hand, wann Sie Ihre Skripte auf die neue REST-API-Version aktualisieren.
 ifdef::onprem[]
-Im Artikel zum xref:update_major#rest_api[Update auf Version {current-major}] finden Sie aktuelle Informationen über den empfohlenen Umgang mit den in einer {CMK}-Major-Version jeweils unterstützten REST-API-Versionen.
+Im Artikel zum xref:update_major#rest_api[Update auf Version {current-major}] finden Sie aktuelle Informationen über den empfohlenen Umgang mit den in dieser {CMK}-Major-Version unterstützten REST-API-Versionen.
 endif::[]
 
 [TIP]
@@ -119,7 +119,7 @@ image::restapi_help_menu.png[alt="Help-Menü in der Navigationsleiste.",width=60
 
 Mit dem Menüpunkt [.guihint]#Introduction# können Sie diesen Artikel öffnen.
 Neben dem Eintrag [.guihint]#Documentation# gibt es für jede Major-Version der REST-API außerdem die Möglichkeit, mit [.guihint]#Interactive GUI# die xref:#rest_api_gui[interaktive GUI] der REST-API zu öffnen.
-Hinweise zur Nutzung der `unstable`-Version der REST-API finden Sie ebenfalls in einem eigenen xref:#unstable[Abschnitt] dieses Artikels.
+Hinweise zur Nutzung der `unstable`-Version der REST-API finden Sie in einem eigenen xref:#unstable[Abschnitt] dieses Artikels.
 
 Wenn Sie im [.guihint]#Help#-Menü den Eintrag [.guihint]#Documentation# für die gewünschte API-Version auswählen, wird die API-Dokumentation in einem neuen Browser-Fenster (bzw. Browser-Tab) angezeigt.
 Sie wurde beim Anlegen Ihrer Instanz mitgeliefert, wurde aber separat mit ReDoc generiert und sieht daher anders aus als die Seiten der {CMK}-Web-GUI.
@@ -140,7 +140,7 @@ Die Endpunkte sind in mehrere Ordner organisiert.
 
 * Der mittlere Inhaltsbereich enthält die harten Fakten der Dokumentation:
 alle Informationen zur Definition einer Anfrage (mit Parametern, Wertebereichen, Default-Werten und Beschreibungen) und die zugehörigen Antworten (ebenfalls mit allen Details).
-Die möglichen Antworten werden in unterschiedlichen Farben dargestellt, je nachdem ob der zurückgelieferte xref:http-status-code[HTTP-Status-Code] Erfolg oder einen Fehler signalisiert.
+Die möglichen Antworten werden in unterschiedlichen Farben dargestellt, je nachdem ob der zurückgelieferte xref:http_status_code[HTTP-Status-Code] Erfolg oder einen Fehler signalisiert.
 
 * Der rechte Beispielbereich ([.guihint]#Request samples#) zeigt für den im Inhaltsbereich ausgewählten Endpunkt die Methode und die URL, gefolgt von mehreren Beispielen zu Anfragen:
 die Payload im JSON-Format (falls relevant für den Endpunkt) und Code-Beispiele z.B. für Python mit `requests`, Python mit `urllib`, Bash mit Httpie und Bash mit Curl.
@@ -154,7 +154,7 @@ Das responsive Web-Design sorgt dafür, dass in einem Browser-Fenster mit gering
 In allen Bereichen finden Sie Inhalte, die Sie ein- und ausblenden können, zum Beispiel im Navigationsbereich die Einträge für die Endpunkte und im Inhaltsbereich verschachtelte Parameter.
 Durch Anklicken von > oder [.guihint]#Expand all# blenden Sie die verborgenen Inhalte ein und mit ∨ oder [.guihint]#Collapse all# wieder aus.
 
-Wie Sie die API-Dokumentation nutzen können, um aus den Informationen konkrete Anfragen zu erstellen, an den {CMK}-Server zu senden, ausführen zu lassen und den Erfolg zu kontrollieren:
+Wie Sie die API-Dokumentation nutzen können, um konkrete Anfragen zu erstellen, an den {CMK}-Server zu senden, ausführen zu lassen und den Erfolg zu kontrollieren:
 all das erfahren Sie im nächsten Kapitel.
 
 
@@ -194,8 +194,8 @@ Beide Informationen müssen im Header jeder Anfrage an den {CMK}-Server übermit
 
 Sie finden Automationsbenutzer, wie andere Benutzer auch, unter [.guihint]#Setup > Users > Users#.
 Um alle Endpunkte der REST-API zu nutzen, brauchen Sie einen Automationsbenutzer mit recht umfangreichen xref:wato_user#roles[Berechtigungen].
-ifdef::onprem[]
 
+ifdef::onprem[]
 .Tipps: Geeigneten Automationsbenutzer anlegen
 [%collapsible]
 ====
@@ -208,7 +208,6 @@ Erstellen Sie als nächstes unter [.guihint]#Setup > Users > Users# einen neuen
 Die Eigenschaften für den neu angelegten Automationsbenutzer konfigurieren Sie so wie im Artikel über xref:wato_user#automation[Benutzer und Berechtigungen] beschrieben.
 Wählen Sie als Rolle die von Ihnen zuvor neu erstellte Rolle, um dem neuen Benutzer so alle benötigten Berechtigungen zuzuweisen.
 ====
-
 endif::[]
 ifdef::saas[]
 Bei einer neu erstellten xref:glossar#site[Instanz] ist der Automationsbenutzer `api_user` bereits angelegt und verfügt über alle benötigten Berechtigungen.
@@ -244,7 +243,7 @@ Die Cookie-Authentifizierung dient zum Ausprobieren und Testen mit der xref:rest
 Ob Anfragen ausgeführt werden können, hängt davon ab, ob Ihr {CMK}-Benutzerkonto die entsprechenden Berechtigungen besitzt.
 
 
-[#http-status-code]
+[#http_status_code]
 === HTTP-Status-Code
 
 Die REST-API gibt zu jeder Anfrage den link:https://de.wikipedia.org/wiki/HTTP-Statuscode[HTTP-Status-Code^] zurück, mit dem Sie überprüfen können, ob die Anfrage erfolgreich war.
@@ -254,7 +253,7 @@ Beachten Sie, dass der HTTP-Status-Code nur Auskunft über die erfolgreiche Übe
 ifdef::onprem[]
 Ausgeführt werden die Befehle auf dem {CMK}-Server mit xref:glossar#livestatus[Livestatus].
 endif::[]
-Um sicher zu sein, dass die Anfrage über die REST-API auch wirklich das bewirkt, was Sie beabsichtigt haben, müssen Sie die Erfolgskontrolle selbst übernehmen. 
+Um sicher zu sein, dass die Anfrage über die REST-API auch wirklich das bewirkt, was Sie beabsichtigt haben, müssen Sie die Erfolgskontrolle selbst übernehmen.
 Die xref:access[API-Dokumentation] enthält im Abschnitt „Queries through the REST API“ ein Beispiel eines Skripts für diese Aufgabe.
 // ES-blocked by KNW-1719: hier auch den Link zum Mirror platzieren mit Anker auf genau diesem Abschnitt
 
@@ -271,7 +270,7 @@ Sie sind also auf jedem Gerät ausführbar, das eine Verbindung zum {CMK}-Server
 endif::[]
 
 Im Folgenden zeigen wir für einige einfache Beispiele Python-Skripte, in denen die HTTP-Anfragen an die API mit dem Modul `requests` umgesetzt sind.
-Alternativ dazu finden Sie für jedes Beispiel auch eine Curl-Variante.
+Daneben finden Sie für jedes Beispiel auch eine Curl-Variante.
 Inhaltlich sind die alternativen Implementierungen deckungsgleich.
 Zu möglichen Unterschieden im Verhalten der verwendeten Werkzeuge, zum Beispiel in Bezug auf Redirects, empfehlen wir einen Blick in die Dokumentation des jeweiligen Tools.
 
@@ -349,7 +348,8 @@ Prinzipiell gehen Sie dabei genauso vor, wie Sie es auch mit der {CMK}-GUI tun w
 .Neben allgemeinen Informationen über den gewählten Endpunkt sehen Sie konkrete Code-Beispiele zur Nutzung
 image::restapi_redoc_2pane.png[alt="Der Eintrag in der API-Dokumentation zum Erstellen eines Hosts.",fullscreen=1]
 
-Im mittleren Bereich sehen Sie die Details zur gewählten Anfrage: welche HTTP-Authentifizierung gefordert ist (diese ist identisch für alle Anfragen über die REST-API) und die notwendigen und optionalen Parameter. Notwendig (_required_) sind der Name des Hosts und der Ordner, in dem er angelegt werden soll.
+Im mittleren Bereich sehen Sie die Details zur gewählten Anfrage: welche HTTP-Authentifizierung gefordert ist (diese ist identisch für alle Anfragen über die REST-API) und die notwendigen und optionalen Parameter.
+Notwendig (_required_) sind der Name des Hosts und der Ordner, in dem er angelegt werden soll.
 Standardmäßig wird der Host im Hauptordner ([.guihint]#Main#) erstellt.
 Falls Sie den Host in einem anderen Ordner anlegen wollen, müssen Sie sich eventuell zuerst über eine andere API-Anfrage ([.guihint]#Show all folders#) die existierenden Ordner anzeigen lassen, um die ID des gewünschten herauszufinden.
 
@@ -414,7 +414,7 @@ Im ersten Teil des Beispiel-Codes finden Sie die Umgebungsvariablen sowie die Ko
 Darunter folgt der `post`-Befehl auf die Ressource, die unter dem angegebenen Pfad zu finden ist, hier also auf den REST-API-Endpunkt `/domain-types/host_config/collections/all`.
 Als Argumente des `post`-Aufrufs werden unter anderem die Parameter für den Request angegeben, in diesem Fall unter anderem der Name für den neu zu erzeugenden Host, der Ordner, in dem er angelegt werden soll und seine IP-Adresse.
 
-Falls die Anfrage erfolgreich war (xref:http-status-code[HTTP-Status-Code] 200 oder 201), folgt nach dem `post`-Befehl eine einfache Ausgabe der Antwort von der API auf den Request.
+Falls die Anfrage erfolgreich war (xref:http_status_code[HTTP-Status-Code] 200 oder 201), folgt nach dem `post`-Befehl eine einfache Ausgabe der Antwort von der API auf den Request.
 Andernfalls wird eine Exception geworfen, deren Beschreibung die Antwort von der API enthält.
 --
 [#create_host_curl]#Bash mit curl#::
@@ -463,15 +463,15 @@ Darunter folgt der `curl`-Befehl mit der POST-Methode auf die Ressource, deren U
 Nach den Header-Zeilen (eine davon definiert die HTTP-Authentifizierung) folgt der Datenteil, in dem die Parameter für den neuen Host festgelegt werden.
 
 Die Antwort der API auf die Anfrage wird als JSON-Objekt ausgegeben.
-Durch die Option `--write-out` erhalten Sie außerdem abschließend eine Zeile mit dem xref:http-status-code[HTTP-Status-Code].
+Durch die Option `--write-out` erhalten Sie außerdem abschließend eine Zeile mit dem xref:http_status_code[HTTP-Status-Code].
 --
 ====
 
-In unserem Beispiel soll der Host `myhost123` mit der IP-Adresse `192.168.0.42` im Hauptordner erstellt werden.
+In diesem Beispiel soll der Host `myhost123` mit der IP-Adresse `192.168.0.42` im Hauptordner erstellt werden.
 
 Beachten Sie, dass der Beispiel-Code aus der API-Dokumentation mehr Parameter enthalten kann, als Sie im konkreten Fall vielleicht benötigen.
-Für unser Beispiel ist dies aber nicht der Fall, und Sie müssen nur die beiden vorhandenen Parameter `host_name` und `ipaddress` ändern.
-Fügen Sie außerdem die richtigen Werte für die Umgebungsvariablen ein, um Ihre spezifische {CMK}-Konfiguration korrekt anzusteuern.
+Für das aktuelle Beispiel ist dies aber nicht der Fall, und Sie müssen nur die beiden vorhandenen Parameter `host_name` und `ipaddress` ändern.
+Fügen Sie außerdem die richtigen Werte für die Umgebungsvariablen ein, um Ihre spezifische {CMK}-Instanz korrekt anzusteuern.
 Ihr angepasstes Skript sollte ungefähr so aussehen:
 
 [.tabs]
@@ -799,7 +799,7 @@ Done
 ----
 
 Wenn die gewünschte Service-Erkennung mit den angegebenen Werten möglich ist, wird die Erkennung als Hintergrundauftrag angestoßen.
-Sie werden außerdem an einen anderen Endpunkt der API weitergeleitet (_redirect_), der im Erfolgsfall den HTTP-Status-Code `204` zurückgibt.
+Sie werden an einen anderen Endpunkt der API weitergeleitet (_redirect_), der im Erfolgsfall den HTTP-Status-Code `204` zurückgibt.
 Dieser Code informiert Sie darüber, dass die Aktion erfolgreich war und planmäßig keine inhaltliche Antwort von der API erfolgt ist.
 --
 [#service_discovery_curl_results]#Bash mit curl#::
@@ -903,7 +903,6 @@ curl \
 --
 ====
 
-
 Nach der Ausführung des Skripts werden in der Ausgabe nun zuerst die Header-Zeilen gezeigt.
 Die Beispiel-Ausgaben hier sind gekürzt.
 Hervorgehoben sind das ETag im Header, die Attribute der zwei ausstehenden Änderungen (Host anlegen und Service-Erkennung durchführen) und der HTTP-Status-Code.
@@ -987,7 +986,7 @@ Das ETag benötigen Sie im nächsten und letzten Schritt.
 Zum Abschluss müssen die Änderungen aktiviert werden.
 Die passende Anfrage heißt [.guihint]#Activate pending changes#.
 
-Im kopierten Code aus der API-Dokumentation ändern Sie die Header-Zeile `If-Match` und setzen Sie dort das im vorherigen Abschnitt ausgelesene ETag ein.
+Kopieren Sie den Code aus der API-Dokumentation, ändern Sie die Header-Zeile `If-Match` und setzen Sie dort das im vorherigen Abschnitt ausgelesene ETag ein.
 Im Datenteil geben Sie für den Parameter `sites` den Namen der Instanz ein -- dort, wo die Änderungen aktiviert werden sollen.
 
 [.tabs]
@@ -1078,7 +1077,6 @@ curl -L \
 --
 ====
 
-
 Führen Sie das Skript aus:
 
 [.tabs]
@@ -1201,7 +1199,7 @@ Zusätzlich zur ausführlichen Dokumentation der REST-API, die oben vorgestellt
 die interaktive GUI der REST-API, die einen direkten API-Zugriff auf die {CMK}-Instanz aus dem Browser heraus ermöglicht.
 Die interaktive GUI wird mit Swagger erzeugt und ist im Hilfe-Menü Ihrer {CMK}-Instanz verlinkt.
 
-Während die API-Dokumentation selbst auch hier auf docs.checkmk.com zur Verfügung gestellt wird, bieten wir keinen Mirror für die interaktive GUI an.
+// Während die API-Dokumentation selbst auch hier auf docs.checkmk.com zur Verfügung gestellt wird, bieten wir keinen Mirror für die interaktive GUI an.
 // ES-blocked by KNW-1719: Link einfügen und sinnvoll darstellen, sobald das möglich ist
 Die interaktive GUI ist genau auf _Ihre_ Instanz von {CMK} zugeschnitten -- und somit kann sie auch nur innerhalb von Ihrer Umgebung genutzt werden.
 
@@ -1211,7 +1209,7 @@ Daraufhin erhalten Sie direkt in der interaktiven GUI die übersichtlich aufbere
 
 Da bestimmte Endpunkte nicht in isolierter Form ohne Kontext angesprochen werden können, bildet die interaktive GUI nur eine Teilmenge der API-Funktionalität ab.
 
-Sie öffnen die interaktive GUI in der {CMK}-GUI über die Navigationsleiste im Menü [.guihint]#Help > Developer resources > REST API > Version 1 > Interactive GUI#.
+Sie öffnen die interaktive GUI aus der {CMK}-GUI über die Navigationsleiste im Menü [.guihint]#Help > Developer resources > REST API > Version 1 > Interactive GUI#.
 Die interaktive GUI wird in einem neuen Browser-Fenster (bzw. Browser-Tab) angezeigt:
 
 .Mit [.guihint]#Try it out# haben Sie die Möglichkeit, die vorbereiteten API-Anfragen um eigene Werte zu ergänzen und sie dann abzuschicken
@@ -1236,7 +1234,7 @@ Klicken Sie [.guihint]#Execute#.
 
 . Antwort überprüfen:
 Unter [.guihint]#Responses# sehen Sie zunächst das gesendete Curl-Kommando und die URL des Endpunkts.
-Anschließend wird unter [.guihint]#Server response# die Antwort angezeigt mit HTTP-Status-Code und in [.guihint]#Details# die (mehrzeilig formatierte) REST-API Antwort.
+Darunter wird unter [.guihint]#Server response# die Antwort angezeigt mit HTTP-Status-Code und in [.guihint]#Details# die (mehrzeilig formatierte) REST-API Antwort.
 
 Die interaktive GUI der REST-API bietet Ihnen also die Möglichkeit, schnell und unkompliziert die Funktionen der API auszuprobieren und sich mit den Details der Eingabewerte und mit konkreten Antworten vertraut zu machen.
 
@@ -1263,7 +1261,7 @@ Hier können Sie hilfreiche Informationen ablesen, die Ihnen helfen, dem zugrund
 ----
 
 Je nach Fehler können die in der Ausgabe angezeigten Parameter unterschiedlich sein.
-Immer erhalten Sie aber -- wie auch bei erfolgreichen Anfragen -- in `status` den xref:http-status-code[HTTP-Status-Code] und in `title` eine Kurzbeschreibung der Rückmeldung von der API.
+Immer erhalten Sie aber -- wie auch bei erfolgreichen Anfragen -- in `status` den xref:http_status_code[HTTP-Status-Code] und in `title` eine Kurzbeschreibung der Rückmeldung von der API.
 
 In den meisten Fällen zeigt Ihnen `detail`, wie der Name schon vermuten lässt, detaillierte Informationen an.
 Im obigen Beispiel erfahren Sie, dass es zwar ausstehende Änderungen in {CMK} gibt, diese aber nicht mit der durchgeführten API-Anfrage aktiviert werden dürfen.
@@ -1289,7 +1287,7 @@ Auch im nächsten Beispiel stecken die hilfreichen in den detaillierten Informat
 
 Hier liegt das Problem darin, dass ein Parameterwert sich nicht an den gültigen Wertebereich hält (wegen eines Schrägstrichs im Host-Namen).
 
-Die Anzahl der möglichen Fehler ist natürlich sehr viel länger als die beiden, die wir vorgestellt haben.
+In diesem Handbuchartikel sollen nicht sämtliche möglichen Fehler von API-Anfragen aufgelistet werden.
 An den gezeigten Beispielen sehen Sie aber, dass die REST-API in der Ausgabe meist genügend Informationen über die Ursache liefert und Ihnen so Anhaltspunkte für den Einstieg in die Analyse und die Fehlerbehebung gibt.
 
 
@@ -1316,7 +1314,7 @@ endif::[]
 ====
 Wie der Name schon andeutet, gilt für die Funktionalität der REST-API in der `unstable`-Version keine Garantie und kein Anspruch auf Support.
 Experimentelle Endpunkte können jederzeit und ohne Vorwarnung geändert oder abgeschaltet werden.
-Im produktiven Betrieb sollten Sie immer nur Endpunkte von Versionen der REST-API ansteuern, die zu einer von Ihrer {CMK}-Instanz unterstützten Version der REST-API gehören!
+Im produktiven Betrieb sollten Sie immer nur Endpunkte der REST-API ansteuern, die zu einer von Ihrer {CMK}-Instanz unterstützten Version der REST-API gehören!
 ====
 
 ifdef::onprem[]