Import aus OpenAPI / Swagger

Wenn Sie Ihre API bereits mit einer OpenAPI-3.x- oder Swagger-2.0-Spezifikation beschreiben, müssen Sie nicht jeden Endpunkt von Hand in LoadFocus nachbauen. Importieren Sie die Spezifikation, und LoadFocus erzeugt einen API-Monitor pro Operation, Methode, URL und eine Statuscode-Prüfung, in einem einzigen Schritt.

Sowohl JSON als auch YAML werden akzeptiert. Die Checks werden in Ihrem aktiven Team angelegt und zählen auf Ihre Tariflimits, genau so, als hätten Sie sie von Hand erstellt.

So funktioniert es

1. Öffnen Sie API Monitoring und gehen Sie zur Liste der Checks.
2. Klicken Sie auf Neuer Monitor und wählen Sie dann in der Gruppe Synthetic OpenAPI importieren.
3. Wählen Sie Spezifikation einfügen und fügen Sie den Spezifikationstext ein, oder wählen Sie Von URL und geben Sie eine Adresse ein, die LoadFocus für Sie lädt.
4. Stellen Sie die Häufigkeit ein, legen Sie fest, ob Importierte Checks jetzt aktivieren angehakt ist, und füllen Sie Basis-URL überschreiben nur aus, wenn Ihre Spezifikation keinen Server enthält.
5. Klicken Sie auf Importieren. LoadFocus liest die Spezifikation und erstellt für jede Operation einen Check.

Für jede Operation erstellt LoadFocus:

• die Anfrage-URL aus servers der Spezifikation (OpenAPI 3) oder schemes + host + basePath (Swagger 2), verbunden mit dem Operationspfad;
• die HTTP-Methode (GET, POST, PUT, PATCH, DELETE, HEAD oder OPTIONS);
• eine Statuscode-Prüfung: den ersten dokumentierten 2xx-Erfolgscode, wenn die Spezifikation einen angibt, sonst eine Prüfung, dass der Statuscode unter 400 liegt;
• einen lesbaren Namen aus der operationId der Operation (oder METHODE /pfad).

Pfadparameter wie /users/{id} werden mit dem example-, default- oder ersten enum-Wert des Parameters gefüllt, sofern die Spezifikation einen liefert. Andernfalls wird für Integer- und Number-Parameter 1 und für alle übrigen der Text example verwendet. Prüfen Sie diese Checks nach dem Import, damit sie auf eine echte Ressource zeigen.

Jeder importierte Check läuft von einem Standort, US East (N. Virginia). Bearbeiten Sie einen Check anschließend, wenn Sie mehr Standorte möchten.

Quelle: Einfügen oder URL

• Spezifikation einfügen: Kopieren Sie den Inhalt Ihrer openapi.json, openapi.yaml, swagger.json oder swagger.yaml in das Feld. Eine Spezifikation darf bis zu etwa 5 MB groß sein und bis zu 500 Operationen beschreiben.
• Von URL: Geben Sie die öffentliche Adresse Ihrer Spezifikation an (zum Beispiel https://api.example.com/openapi.json). Die Adresse muss mit https:// beginnen, Weiterleitungen werden nicht verfolgt, und interne oder private Adressen werden abgelehnt. Dasselbe Größenlimit gilt.

Basis-URL

LoadFocus liest die Basis-URL aus der Spezifikation: den ersten Eintrag von servers bei OpenAPI 3 oder schemes, host und basePath bei Swagger 2. Gibt die Spezifikation keinen an (oder ist ihr erster Server ein relativer Pfad), füllen Sie Basis-URL überschreiben aus, zum Beispiel https://api.example.com. Die Überschreibung ist nur ein Fallback: Hat die Spezifikation einen brauchbaren Server, wird dieser verwendet und die Überschreibung ignoriert. Um gegen einen Staging-Host zu importieren, setzen Sie ihn an den Anfang der servers-Liste der Spezifikation.

Häufigkeit und Aktivierung

• Häufigkeit: wie oft jeder importierte Check läuft. Wählen Sie 5, 10, 15 oder 30 Minuten oder 1 Stunde; 5 Minuten sind der Standard.
• Aktivieren (Importierte Checks jetzt aktivieren): Wenn angehakt, starten die Checks sofort. Nehmen Sie den Haken weg, um sie pausiert zu importieren, zu prüfen und nur die gewünschten zu aktivieren. Das ist nützlich, wenn Ihre Spezifikation Schreiboperationen (POST, PUT, DELETE) enthält, die ein geplanter Monitor nicht wiederholt aufrufen soll.

Was Sie nach dem Import prüfen sollten

• Schreiboperationen: Ein geplanter Monitor ruft den Endpunkt bei jedem Lauf auf. Bestätigen Sie bei POST, PUT, PATCH und DELETE, dass Sie sie wirklich überwachen möchten, oder importieren Sie pausiert und aktivieren nur die sicheren.
• Pfadparameter: Stellen Sie sicher, dass ersetzte Werte auf eine vorhandene Ressource zeigen.
• Authentifizierung: Importierte Checks haben überhaupt keine Header. Fügen Sie die Header hinzu, die Ihre API braucht, etwa einen API-Schlüssel oder ein Token, über Variablen und Secrets, damit authentifizierte Endpunkte ihren echten Status zurückgeben.
• Anfrage-Bodies: Bei einer OpenAPI-3-Operation, deren Request-Body ein Beispiel hat, wird dieses Beispiel als Body gesendet. In allen anderen Fällen, auch bei allen Swagger-2-Operationen, wird die Anfrage ohne Body gesendet.

Plan-Limits

Importierte Checks zählen zum API-Monitor-Limit Ihres Plans, genau wie von Hand erstellte Checks. Hat eine Spezifikation mehr Operationen als Ihr verbleibendes Kontingent, erstellt LoadFocus so viele wie möglich und meldet, wie viele erstellt und wie viele übersprungen wurden: nichts wird über Ihren Plan hinaus still erstellt.

Monitore synchron halten

Ein einmaliger Import ist ein schneller Einstieg. Wenn Ihre Monitore mit Ihrer API-Definition dauerhaft im Gleichschritt bleiben sollen, verwalten Sie sie als versionierte Dateien mit Monitoring as Code und gleichen Sie sie aus CI ab.