Geekly articles weekly

Automatisierung für die Kleinsten. Hinweise. RESTful API

Dieser Artikel ist einer der versprochenen Kurznotizen in der Artikelserie Automation For The Smallest .
Da die Hauptmethode für die Interaktion mit dem IPAM-System die RESTful-API ist, habe ich mich dazu entschlossen, separat darüber zu sprechen.


Ich preise Architekten der modernen Welt - wir haben standardisierte Schnittstellen. Ja, es gibt viele von ihnen - das ist ein Minus, aber sie sind es - das ist ein Plus.

Diese Schnittstellen haben den Namen API - Application Programming Interface erhalten.

Eine dieser Schnittstellen ist die RESTful-API, die für die Arbeit mit NetBox verwendet wird.



Wenn es sehr einfach ist, bietet die API dem Client eine Reihe von Tools, mit denen er den Server verwalten kann. Und der Client kann im Wesentlichen alles sein: ein Webbrowser, eine Befehlskonsole, eine vom Hersteller entwickelte Anwendung oder jede andere Anwendung, die Zugriff auf die API hat.

Im Falle von NetBox können Sie dem Gerät beispielsweise auf folgende Weise ein neues Gerät hinzufügen: Senden Sie über einen Webbrowser eine Anfrage in der Konsole, verwenden Sie Postman, greifen Sie auf die Anforderungsbibliothek in Python zu, verwenden Sie das Pynetbox-SDK oder rufen Sie Swagger auf.

Sobald ein einzelnes Interface geschrieben wurde, muss der Hersteller für immer nicht mehr mit jedem neuen Client absprechen, wie er es verbindet (obwohl dies nur ein bisschen gerissen ist).

Inhalt


  • REST, RESTful, API
  • HTTP-Nachrichtenstruktur
    • Startzeile
    • Überschriften
    • Der Hauptteil der HTTP-Nachricht

  • Methoden
    • HTTP GET
    • HTTP POST
    • HTTP PUT
    • HTTP PATCH
    • HTTP LÖSCHEN

  • Möglichkeiten zum Arbeiten mit der RESTful-API
    • Curl
    • Briefträger
    • Python + Anfragen
    • Pynebtbox SDK
    • Prahlerei

  • Kritik an REST und Alternativen
  • Nützliche Links

REST, RESTful, API


Im Folgenden werde ich sehr vereinfacht beschreiben, was REST ist.

Zunächst ist die RESTful-API genau die REST-basierte Interaktionsschnittstelle, während REST ( REpresentational State Transfer ) selbst eine Reihe von Einschränkungen darstellt, die zum Erstellen von WEB-Diensten verwendet werden.

Es ist möglich, genau zu lesen, welche Einschränkungen in Kapitel 5 der Dissertation von Roy Fielding, Architekturstile und Entwurf netzwerkbasierter Softwarearchitekturen zu finden sind . Lassen Sie mich nur die drei wichtigsten (aus meiner Sicht) nennen:

  1. Die REST-Architektur verwendet das Client-Server-Interaktionsmodell.
  2. Jede REST-Anforderung enthält alle für ihre Ausführung erforderlichen Informationen. Das heißt, der Server sollte sich an keine früheren Client-Anforderungen erinnern, die, wie Sie wissen, durch das Wort Stateless gekennzeichnet sind - wir speichern keine Statusinformationen.
  3. Einheitliche Schnittstelle. Die Implementierung der Anwendung unterscheidet sich von dem Dienst, den sie bereitstellt. Das heißt, der Benutzer weiß, was er tut und wie er damit umgehen soll, aber wie er es tut, spielt keine Rolle. Wenn Sie die Anwendung ändern, bleibt die Benutzeroberfläche unverändert, und die Clients müssen nicht angepasst werden.

WEB-Dienste, die alle Prinzipien von REST erfüllen, werden als RESTful WEB-Dienste bezeichnet .

Die API, die RESTful-WEB-Dienste bereitstellt, wird als RESTful-API bezeichnet.

REST ist kein Protokoll, sondern der sogenannte Architekturstil (einer von). REST wurde mit HTTP von Roy Fielding entwickelt und sollte HTTP 1.1 als Transport verwenden.

Zieladresse (oder mit anderen Worten - ein Objekt oder auf andere Weise - ein Endpunkt) - dies ist unsere übliche URI .

Das Format der übertragenen Daten ist XML oder JSON .
Für diese Artikelserie zu linkmeup wurde eine schreibgeschützte Bereitstellung bereitgestellt (für Sie, liebe Leser). NetBox-Installation: netbox.linkmeup.ru : 45127.

Leserechte sind nicht erforderlich. Wenn Sie jedoch versuchen möchten, mit einem Token zu lesen, können Sie Folgendes verwenden: Token-API: 90a22967d0bc4bdcd8ca47ec490bbf0b0cb2d9c8 .
Lassen Sie uns eine Anfrage zum Spaß machen:

curl -X GET -H "Authorization: TOKEN 90a22967d0bc4bdcd8ca47ec490bbf0b0cb2d9c8" \ -H "Accept: application/json; indent=4" \ http://netbox.linkmeup.ru:45127/api/dcim/devices/1/

Mit dem Dienstprogramm curl erstellen wir ein GET- Objekt unter netbox.linkmeup.ru : 45127 / api / dcim / devices / 1 / mit einer Antwort im JSON-Format und einem Einzug von 4 Leerzeichen.

Oder etwas akademischer: GET gibt das typisierte Geräteobjekt zurück , das ein Parameter des DCIM- Objekts ist.

Diesen Wunsch können Sie auch erfüllen - kopieren Sie ihn einfach auf Ihr Terminal.
Die URL, auf die wir in der Anfrage verweisen, heißt Endpoint . In gewissem Sinne ist dies das letzte Objekt, mit dem wir interagieren werden.
Im Falle von netbox kann hier beispielsweise eine Liste aller Endpunkte abgerufen werden .
Und achten Sie auf das / -Zeichen am Ende der URL - es ist erforderlich .
Folgendes erhalten wir als Antwort:

 { "id": 1, "name": "mlg-host-0", "display_name": "mlg-host-0", "device_type": { "id": 4, "url": "http://netbox.linkmeup.ru/api/dcim/device-types/4/", "manufacturer": { "id": 4, "url": "http://netbox.linkmeup.ru/api/dcim/manufacturers/4/", "name": "Hypermacro", "slug": "hypermacro" }, "model": "Server", "slug": "server", "display_name": "Hypermacro Server" }, "device_role": { "id": 1, "url": "http://netbox.linkmeup.ru/api/dcim/device-roles/1/", "name": "Server", "slug": "server" }, "tenant": null, "platform": null, "serial": "", "asset_tag": null, "site": { "id": 6, "url": "http://netbox.linkmeup.ru/api/dcim/sites/6/", "name": "", "slug": "mlg" }, "rack": { "id": 1, "url": "http://netbox.linkmeup.ru/api/dcim/racks/1/", "name": "A", "display_name": "A" }, "position": 41, "face": { "value": "front", "label": "Front", "id": 0 }, "parent_device": null, "status": { "value": "active", "label": "Active", "id": 1 }, "primary_ip": null, "primary_ip4": null, "primary_ip6": null, "cluster": null, "virtual_chassis": null, "vc_position": null, "vc_priority": null, "comments": "", "local_context_data": null, "tags": [], "custom_fields": {}, "config_context": {}, "created": "2020-01-14", "last_updated": "2020-01-14T18:39:01.288081Z" }

Dies ist JSON (wie von uns angefordert), das das Gerät mit der ID 1 beschreibt: Wie heißt es, mit welcher Rolle, welchem ​​Modell, wo steht es usw.

Dies sieht aus wie eine HTTP-Anfrage:

  GET /api/dcim/devices/1/ HTTP/1.1 Host: netbox.linkmeup.ru:45127 User-Agent: curl/7.54.0 Accept: application/json; indent=4


So wird die Antwort aussehen:
  HTTP/1.1 200 OK Server: nginx/1.14.0 (Ubuntu) Date: Tue, 21 Jan 2020 15:14:22 GMT Content-Type: application/json Content-Length: 1638 Connection: keep-alive Data

Sichern Sie die Transaktion .

Lassen Sie uns nun herausfinden, was wir getan haben.


HTTP-Nachrichtenstruktur


Eine HTTP-Nachricht besteht aus drei Teilen, von denen nur der erste erforderlich ist.

  • Startzeile
  • Überschriften
  • Nachrichtentext

Startzeile


Die Startzeilen der HTTP-Anforderung und -Antwort sehen unterschiedlich aus.

HTTP-Anfrage


 METHOD URI HTTP_VERSION

Die Methode bestimmt, welche Aktion der Client ausführen möchte: Daten empfangen, ein Objekt erstellen, aktualisieren, löschen.
URI - Die ID der Ressource, auf die der Client zugreift, oder mit anderen Worten, der Pfad zur Ressource / zum Dokument.
HTTP_VERSION ist die jeweilige HTTP-Version. Für REST ist es heute immer 1.1.
Ein Beispiel:

 GET /api/dcim/devices/1/ HTTP/1.1


HTTP-Antwort


 HTTP_VERSION STATUS_CODE REASON_PHRASE

HTTP_VERSION - HTTP-Version (1.1).
STATUS_CODE - drei Ziffern des Statuscodes (200, 404, 502 usw.)
REASON_PHRASE - Erläuterung (OK, NOT FOUND, BAD GATEWAY usw.)

Ein Beispiel:

 HTTP/1.1 200 OK

Überschriften


Die Header übergeben die Parameter für diese HTTP-Transaktion.

Im obigen Beispiel in der HTTP-Anforderung waren dies beispielsweise:

  Host: netbox.linkmeup.ru:45127 User-Agent: curl/7.54.0 Accept: application/json; indent=4

Sie zeigen das an

  1. Wir wenden uns an den Host netbox.linkmeup.ru:45127 ,
  2. Die Anfrage wurde in curl generiert,
  3. Und wir akzeptieren Daten im JSON-Format mit einem Einzug von 4 .

Und hier sind die Überschriften in der HTTP-Antwort:

  Server: nginx/1.14.0 (Ubuntu) Date: Tue, 21 Jan 2020 15:14:22 GMT Content-Type: application/json Content-Length: 1638 Connection: keep-alive

Sie zeigen das an

  1. Servertyp: nginx unter Ubuntu ,
  2. Reaktionszeit
  3. Antwortdatenformat: JSON
  4. Antwortdatenlänge: 1638 Byte
  5. Die Verbindung muss nicht geschlossen werden - es sind noch Daten vorhanden.

Wie Sie bereits bemerkt haben, sehen die Überschriften wie Name: Wert-Paare aus, die durch ein ":" - Zeichen getrennt sind.

Eine vollständige Liste der möglichen Überschriften .

Der Hauptteil der HTTP-Nachricht


Der Körper wird verwendet, um die tatsächlichen Daten zu übertragen.

In der HTTP-Antwort kann dies eine HTML-Seite oder in unserem Fall ein JSON-Objekt sein.

Zwischen den Headern und dem Body muss mindestens eine Leerzeile sein.

Bei Verwendung der GET-Methode in einer HTTP-Anforderung gibt es normalerweise keinen Body, da nichts zu übertragen ist. Aber der Körper ist in der HTTP-Antwort.

Bei POST ist der Body beispielsweise bereits in der Anfrage enthalten. Sprechen wir über die Methoden und sprechen wir jetzt.


Methoden


Wie Sie bereits verstanden haben, verwendet HTTP Methoden, um mit WEB-Diensten zu arbeiten. Gleiches gilt für die RESTful-API.

Mögliche reale Szenarien werden durch den Begriff CRUD - Erstellen, Lesen, Aktualisieren, Löschen beschrieben .
Hier ist eine Liste der beliebtesten HTTP-Methoden, die CRUD implementieren:

  • HTTP GET
  • HTTP POST
  • HTTP PUT
  • HTTP LÖSCHEN
  • HTTP PATCH

Methoden werden auch als Verben bezeichnet , da sie angeben, welche Aktion ausgeführt wird.

Vollständige Liste der Methoden .

Schauen wir uns jeden einzelnen anhand des NetBox-Beispiels an.

HTTP GET


Dies ist eine Methode, um Informationen zu erhalten.

So nehmen wir zum Beispiel die Liste der Geräte weg:

 curl -H "Accept: application/json; indent=4" \ http://netbox.linkmeup.ru:45127/api/dcim/devices/

Die Methode GET ist sicher, da sie keine Daten ändert, sondern nur fragt.

Es ist aus der Sicht idempotent, dass dieselbe Abfrage immer dasselbe Ergebnis liefert (bis sich die Daten selbst geändert haben).

Bei GET gibt der Server eine Nachricht mit dem HTTP-Code und dem Antworttext ( Antwortcode und Antworttext ) zurück.

Das heißt, wenn alles in Ordnung ist, lautet der Antwortcode 200 (OK).
Wird die URL nicht gefunden, 404 (NOT FOUND).
Wenn etwas mit dem Server oder den Komponenten selbst nicht stimmt, kann dies 500 (SERVER ERROR) oder 502 (BAD GATEWAY) sein.
Alle möglichen Antwortcodes .

Der Body wird im JSON- oder XML-Format zurückgegeben.

Sichern Sie die Transaktion .

Lassen Sie uns noch ein paar Beispiele nennen. Nun fordern wir Informationen zu einem bestimmten Gerät mit seinem Namen an.

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?name=mlg-leaf-0"

Um die Suchbedingungen in der URI festzulegen, habe ich hier auch den Attribut des Objekts angegeben (den Parameter name und seinen Wert mlg-leaf-0 ). Wie Sie sehen, steht vor der Bedingung und nach dem Schrägstrich ein "?" , und der Name und der Wert werden durch ein "=" getrennt .

So sieht die Anfrage aus.

  GET /api/dcim/devices/?name=mlg-leaf-0 HTTP/1.1 Host: netbox.linkmeup.ru:45127 User-Agent: curl/7.54.0 Accept: application/json; indent=4

Sichern Sie die Transaktion .

Wenn Sie einige Bedingungen angeben müssen, sieht die Abfrage folgendermaßen aus:

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?role=leaf&site=mlg"

Hier haben wir alle Blattgeräte angefordert, die sich auf der mlg- Website befinden.
Das heißt, die beiden Bedingungen sind durch das Zeichen "&" voneinander getrennt.

Sichern Sie die Transaktion .

Aus dem Neugierigen und Angenehmen - wenn Sie durch "&" zwei Bedingungen mit demselben Namen setzen, dann wird zwischen ihnen tatsächlich kein logisches "UND", sondern ein logisches "ODER" stehen.

Das heißt, eine solche Abfrage gibt tatsächlich zwei Objekte zurück: mlg-leaf-0 und mlg-spine-0

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?name=mlg-leaf-0&name=mlg-spine-0"

Sichern Sie die Transaktion .

Versuchen wir, auf eine nicht vorhandene URL zuzugreifen.

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/IDGAF/"

Sichern Sie die Transaktion .


HTTP POST


POST wird verwendet, um ein neues Objekt in einer Sammlung von Objekten zu erstellen. Oder in einer komplexeren Sprache: um eine neue untergeordnete Ressource zu erstellen.

Klarstellung von arthuriantech :
Einschließlich, aber nicht beschränkt auf. Die POST-Methode dient dazu, Daten zur weiteren Verarbeitung auf den Server zu übertragen. Sie wird für alle Aktionen verwendet, die nicht innerhalb von HTTP standardisiert werden müssen. Vor RFC 5789 war dies die einzige rechtliche Möglichkeit, teilweise Änderungen vorzunehmen.
roy.gbiv.com/untangled/2009/it-is-okay-to-use-post
tools.ietf.org/html/rfc7231#section-4.3.3


Wenn also mehrere Geräte vorhanden sind, können Sie mit POST ein neues Geräteobjekt in Geräten erstellen.

Wählen Sie denselben Endpunkt aus und erstellen Sie mit POST ein neues Gerät.

 curl -X POST "http://netbox.linkmeup.ru:45127/api/dcim/devices/" \ -H "accept: application/json"\ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"name\": \"just a simple russian girl\", \"device_type\": 1, \"device_role\": 1, \"site\": 3, \"rack\": 3, \"position\": 5, \"face\": \"front\"}"

Hier wird bereits ein Authorization- Header angezeigt, der ein Token enthält, das die Schreibanforderung autorisiert. Nach der Anweisung -d befindet sich JSON mit den Parametern des erstellten Geräts:

 { "name": "just a simple russian girl", "device_type": 1, "device_role": 1, "site": 3, "rack": 3, "position": 5, "face": "front"}

Ihre Anfrage wird nicht funktionieren, da das Token nicht mehr gültig ist. Versuchen Sie nicht, in die NetBox zu schreiben.
Die Antwort enthält eine HTTP-Antwort mit dem Code 201 (CREATED) und JSON im Nachrichtentext, wobei der Server alle Parameter zum erstellten Gerät zurückgibt.

  HTTP/1.1 201 Created Server: nginx/1.14.0 (Ubuntu) Date: Sat, 18 Jan 2020 11:00:22 GMT Content-Type: application/json Content-Length: 1123 Connection: keep-alive JSON

Sichern Sie die Transaktion .

Bei einer neuen Anforderung mit der GET-Methode können Sie dies nun in der Ausgabe sehen:

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?q=russian"

"Q" in NetBox ermöglicht es Ihnen, alle Objekte zu finden, die in ihrem Namen eine Zeile enthalten, die weiter geht.
POST ist offensichtlich weder sicher noch idempotent - es ändert wahrscheinlich die Daten, und eine doppelt ausgeführte Anforderung führt entweder zur Erstellung des zweiten gleichen Objekts oder zu einem Fehler.


HTTP PUT


Dies ist eine Methode zum Ändern eines vorhandenen Objekts. Der Endpunkt für PUT sieht anders aus als für POST - er enthält jetzt ein bestimmtes Objekt.

PUT kann die Codes 201 oder 200 zurückgeben.

Ein wichtiger Punkt bei dieser Methode: Sie müssen alle erforderlichen Attribute übergeben, da PUT das alte Objekt ersetzt.

Wenn wir also beispielsweise nur versuchen, das Attribut asset_tag zu unserem neuen Gerät hinzuzufügen, erhalten wir eine Fehlermeldung:

 curl -X PUT "http://netbox.linkmeup.ru:45127/api/dcim/devices/18/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"asset_tag\": \"12345678\"}" 

 {"device_type":["This field is required."],"device_role":["This field is required."],"site":["This field is required."]}

Wenn Sie jedoch die fehlenden Felder hinzufügen, funktioniert alles:

 curl -X PUT "http://netbox.linkmeup.ru:45127/api/dcim/devices/18/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"name\": \"just a simple russian girl\", \"device_type\": 1, \"device_role\": 1, \"site\": 3, \"rack\": 3, \"position\": 5, \"face\": \"front\", \"asset_tag\": \"12345678\"}"

Sichern Sie die Transaktion .
Achten Sie hier auf die URL, die jetzt die ID des zu ändernden Geräts enthält ( 18 ).


HTTP PATCH


Diese Methode wird verwendet, um die Ressource teilweise zu ändern.
Wat? Sie fragen, aber was ist mit Put?

PUT ist eine Methode, die ursprünglich im Standard existierte und die das vollständige Ersetzen eines veränderlichen Objekts beinhaltet. Dementsprechend müssen Sie in der PUT-Methode, wie ich oben geschrieben habe, auch die Attribute des Objekts angeben, die sich nicht ändern.

Und PATCH wurde später hinzugefügt und ermöglicht es Ihnen, nur die Attribute anzugeben, die sich wirklich ändern.

Zum Beispiel:

 curl -X PATCH "http://netbox.linkmeup.ru:45127/api/dcim/devices/18/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"serial\": \"BREAKINGBAD\"}"

Hier wird auch die Geräte-ID in der URL angegeben, es muss jedoch nur ein serielles Attribut geändert werden.

Sichern Sie die Transaktion .


HTTP LÖSCHEN


Offensichtlich löscht das Objekt.

Ein Beispiel.

 curl -X DELETE "http://netbox.linkmeup.ru:45127/api/dcim/devices/21/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f"

Die DELETE-Methode ist aus der Sicht idempotent, dass eine wiederholte Abfrage nichts mehr in der Ressourcenliste ändert (sondern den Code 404 (NOT FOUND) zurückgibt.

 curl -X DELETE "http://netbox.linkmeup.ru:45127/api/dcim/devices/21/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" 

 {"detail":"Not found."}


Möglichkeiten zum Arbeiten mit der RESTful-API


Curl ist natürlich sehr praktisch für die tapferen CLI-Krieger, aber es gibt bessere Werkzeuge.

Briefträger


Mit Postman können Sie Abfragen in der grafischen Benutzeroberfläche erstellen, indem Sie Methoden, Überschriften und Text auswählen und das Ergebnis in einer für Menschen lesbaren Form anzeigen.

Darüber hinaus können Abfragen und URIs gespeichert und später an sie zurückgegeben werden.

Laden Sie Postman auf der offiziellen Website herunter .

Also können wir ein GET machen:


Hier ist Token nur als Beispiel im GET angegeben.

Und so POST:



Postman darf nur mit der RESTful-API verwendet werden.
Versuchen Sie beispielsweise nicht, NETCONF-XML wie zu Beginn meiner Automatisierungskarriere zu senden.
Einer der schönen Vorteile der angegebenen API ist, dass Sie alle Endpunkte und ihre Methoden als Sammlung in Postman importieren können.

Wählen Sie dazu im Fenster Importieren (Datei-> Importieren) die Option Aus Link importieren und fügen Sie sie in das Fenster netbox.linkmeup.ru ein. URL: 45127 / api / docs /? Format = openapi.



Darüber hinaus finden Sie alles in den Sammlungen.





Python + Anfragen


Aber selbst über Postman werden Sie Ihre Produktionssysteme höchstwahrscheinlich nicht verwalten. Sicherlich werden Sie externe Anwendungen haben, die ohne Ihre Teilnahme mit ihnen interagieren möchten.

Ein Konfigurationsgenerierungssystem möchte beispielsweise eine Liste der IP-Schnittstellen von NetBox abrufen.
Python verfügt über eine wunderbare Bibliothek von Anforderungen , die die Arbeit über HTTP implementieren.
Ein Beispiel für das Anfordern einer Liste aller Geräte:

 import requests HEADERS = {'Content-Type': 'application/json', 'Accept': 'application/json'} NB_URL = "http://netbox.linkmeup.ru:45127" request_url = f"{NB_URL}/api/dcim/devices/" devices = requests.get(request_url, headers = HEADERS) print(devices.json())

Fügen Sie erneut ein neues Gerät hinzu:

 import requests API_TOKEN = "a9aae70d65c928a554f9a038b9d4703a1583594f" HEADERS = {'Authorization': f'Token {API_TOKEN}', 'Content-Type': 'application/json', 'Accept': 'application/json'} NB_URL = "http://netbox.linkmeup.ru:45127" request_url = f"{NB_URL}/api/dcim/devices/" device_parameters = { "name": "just a simple REQUESTS girl", "device_type": 1, "device_role": 1, "site": 3, } new_device = requests.post(request_url, headers = HEADERS, json=device_parameters) print(new_device.json())


Python + NetBox SDK


Im Falle von NetBox gibt es auch ein Python SDK - Pynetbox , das alle NetBox-Endpunkte als Objekt und deren Attribute darstellt und die ganze Dirty-Arbeit für Sie erledigt , URIs zu generieren und die Antwort zu analysieren, obwohl dies natürlich nicht kostenlos ist.

Machen wir zum Beispiel dasselbe wie oben mit pynetbox.
Liste aller Geräte:

 import pynetbox NB_URL = "http://netbox.linkmeup.ru:45127" nb = pynetbox.api(NB_URL) devices = nb.dcim.devices.all() print(devices)

Neues Gerät hinzufügen:

 import pynetbox API_TOKEN = "a9aae70d65c928a554f9a038b9d4703a1583594f" NB_URL = "http://netbox.linkmeup.ru:45127" nb = pynetbox.api(NB_URL, token = API_TOKEN) device_parameters = { "name": "just a simple PYNETBOX girl", "device_type": 1, "device_role": 1, "site": 3, } new_device = nb.dcim.devices.create(**device_parameters) print(new_device)

Pynetbox-Dokumentation


Prahlerei


Was dank des letzten Jahrzehnts noch wert ist, sind die API-Spezifikationen. Wenn Sie diesem Pfad folgen, gelangen Sie zur Swagger UI - Netbox API-Dokumentation.



Diese Seite listet alle Endpunkte, Methoden zum Arbeiten mit ihnen, mögliche Parameter und Attribute auf und gibt an, welche von ihnen erforderlich sind. Außerdem werden die erwarteten Antworten beschrieben.



Auf derselben Seite können Sie interaktive Abfragen durchführen, indem Sie auf Ausprobieren klicken.
Aus irgendeinem Grund verwendet swagger den Namen des Servers ohne Port als Basis-URL, sodass die Funktion "Ausprobieren" in meinen Swagger-Beispielen nicht funktioniert. Aber Sie können es auf Ihrer eigenen Installation versuchen.
Wenn Sie auf "Swagger ausführen" klicken, generiert die Benutzeroberfläche eine Curl-Zeichenfolge, mit der über die Befehlszeile eine ähnliche Anforderung gestellt werden kann.

In der Swagger-Benutzeroberfläche können Sie sogar ein Objekt erstellen:



Dazu genügt es, ein autorisierter Benutzer mit den erforderlichen Rechten zu sein.

Was wir auf dieser Seite sehen, ist die Swagger-Benutzeroberfläche, eine Dokumentation, die basierend auf der API-Spezifikation erstellt wurde.

Angesichts der Trends in der Microservice-Architektur wird es immer wichtiger, eine standardisierte API für die Interaktion zwischen Komponenten zu haben, deren Endpunkte und Methoden für die Person und die Anwendung leicht zu bestimmen sind, ohne den Quellcode oder die PDF-Dokumentation zu durchsuchen.

Daher folgen Entwickler heutzutage zunehmend dem API-First- Paradigma, wenn sie zuerst über die API nachdenken und erst dann über die Implementierung.
Die API wird zuerst in diesem Entwurf angegeben. Anschließend werden die Dokumentation, die Clientanwendung und der Serverteil daraus generiert , und es sind Tests erforderlich.

Swagger ist eine Framework- und Spezifikationssprache (die jetzt in OpenAPI 2.0 umbenannt wurde), mit der Sie diese Aufgabe implementieren können.
Ich werde nicht weiter darauf eingehen.

Für mehr Details hier:



Kritik an REST und Alternativen


Da ist einer, ja. Nicht alles in dieser Welt des Jahres 2000 ist schon so rosig.

Da ich kein Experte bin, nehme ich nicht an, das Thema inhaltlich zu offenbaren, aber ich werde einen Link zu einem unbestreitbaren Artikel über Habré geben .

Eine alternative Schnittstelle für das Zusammenspiel von Systemkomponenten ist heute gRPC. Er prophezeite auch eine große Zukunft im Bereich neuer Ansätze für die Arbeit mit Netzwerkgeräten. Aber wir werden irgendwann in der Zukunft über ihn sprechen, wenn er an der Reihe ist.

Sie können auch einen Blick auf das vielversprechende GraphQL werfen , aber auch hier müssen wir vorerst nicht damit arbeiten, so dass es für unabhängige Studien bleibt.


Ist wichtig
Das Token a9aae70d65c928a554f9a038b9d4703a1583594f wurde nur zu Demonstrationszwecken verwendet und funktioniert nicht mehr.

Die direkte Angabe von Tokens im Programmcode ist nicht akzeptabel und ich habe hier nur im Interesse der Vereinfachung der Beispiele gemacht.


Nützliche Links



Vielen Dank


  • Andrei Panfilov zum Korrekturlesen und Bearbeiten
  • Alexander Fatin zum Korrekturlesen und Redigieren

Source: https://habr.com/ru/post/de485618/

More articles:


All Articles