Mit dem API Designer können Sie auf schnellstem Wege eine REST-API (Representational State Transfer Application Programming Interface) erstellen, dokumentieren, kompilieren und veröffentlichen. Diese API basiert auf der OpenAPI-Spezifikation und dem One Identity Manager-Datenbankmodell.
Vorteile des API Designers auf einem Blick:
-
Einfache und schnelle Bedienung
-
Die fertige API "versteht" das One Identity Manager-Datenbankmodell.
-
Änderungen an der API sind nachvollziehbar.
-
Unterstützt Prinzipien eines guten API-Designs
-
OpenAPI-Unterstützung: APIs, die Sie mithilfe des API Designers erstellen, basieren grundsätzlich auf der OpenAPI-Spezifikation. Dies ermöglicht Ihnen auf weitere Hilfsmittel zuzugreifen:
- Swagger: Verwenden Sie Swagger, um Code, Dokumentation und Testfälle zu erstellen.
- Postman: Verwenden Sie Postman, um die verschiedenen API-Methoden Ihrer API zu testen.
Grundlagen der API-Entwicklung
Hauptbestandteil einer mit dem API Designer erstellten API sind Dateien und Projekte.
Grundsätzliches zu API-Dateien:
-
Mit API-Dateien können Sie API-Methoden definieren, mit denen man wiederum Daten an die Anwendung senden oder Daten von der Anwendung abfragen.
-
Eine API-Datei kann zu mehr als einem Projekt gehören.
-
Da der API Server zustandslos ist (stateless), speichern Sie API-Methoden, die Sie in API-Dateien festlegen, ohne Client-spezifischen Zustand.
Sie dürfen daher beispielsweise keine globalen Variablen definieren oder am Session-Objekt Zustandsdaten hinterlegen. Beim Neustart des API Server-Prozesses werden diese Werte nicht wiederhergestellt.
-
Verwenden Sie asynchronen Code beim Definieren von API-Methoden. Damit wird die effiziente Nutzung der Server-Ressourcen unterstützt sowie die System-Performance unter Last verbessert. Die Methoden der API und des zugrundeliegenden Objektmodells setzen diese Asynchronität mithilfe des Task-based Asynchronous Pattern (TAP) um. Weitere Informationen zu TAP finden Sie unter https://docs.microsoft.com/de-de/dotnet/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.
-
Verwenden Sie beim Definieren von API-Methoden NICHT die Methode HttpContext.Current. Die aktuelle HTTP-Anforderung können Sie mit der statischen Methode QBM.CompositionApi.ApiManager.Context.Current abfragen.
Grundsätzliches zu API-Projekten:
Grundsätzliches zum API-Server:
-
Der API Server ist mithilfe der Owin-Plattform implementiert (siehe http://owin.org/).
-
Der Zugriff auf die aktuellen HTTP-Anforderung über ASP.NET-APIs wird nicht unterstützt.
-
Nach dem Aktivieren der Routen dürfen Sie die Definitionsobjekte nicht mehr verändern.
Verwandte Themen
In diesem Kapitel finden Sie Informationen zur Abarbeitung einer Anfrage an den API-Server.
Authentifizierung
Bei einer Anfrage an den API Server wird geprüft, ob in der Sitzung für das jeweilige API-Projekt die primäre und gegebenenfalls sekundäre Anmeldung erfolgt ist (siehe Authentifizierung).
HINWEIS: Diese Prüfung erfolgt nicht, wenn die API-Methode der Anfrage als AllowUnauthenticated markiert ist.
Für die Zuordnung der aktuellen Sitzung wird der vom Client übermittelte Cookie imx-session-<Name des API-Projektes> ausgewertet.
Wenn ein Cookie übermittelt wird, der aber keiner im aktuellen Prozess aktiven Sitzung zugeordnet werden kann, wird mit dem im Cookie enthaltenen Sicherheitstoken eine neue Sitzung hergestellt (siehe Sitzungsstatus und Sicherheitstoken).
Liegt keine primäre Anmeldung vor, versucht der API Server über eines der aktivierten Single-Sign-On-Authentifizierungsmodule eine Datenbankverbindung herzustellen.
Kann die Anmeldung auch dann nicht hergestellt werden, wird die Bearbeitung der Anforderung abgebrochen und der HTTP-Fehlercode 500 wird an den Client übermittelt (siehe Antwortcodes).
Autorisierung des Methodenzugriffs
Der API Server prüft, ob der aktuell angemeldete Benutzer berechtigt ist, die Methode auszuführen. Verfügt der Benutzer nicht über die benötigten Berechtigungen, wird die Bearbeitung abgebrochen und der HTTP-Fehlercode 500 wird an den Client übermittelt (siehe Antwortcodes).
Validierung der Anfrage
Der API Server ruft die an der API-Methode hinterlegten Validatoren nacheinander auf. Wenn ein Fehler zurückgemeldet wird, wird die Bearbeitung abgebrochen und der HTTP-Fehlercode 400 wird an den Client übermittelt (siehe Antwortcodes).
Abarbeitung der Anfrage (für Entity-Methoden)
- GET (Laden von Entities)
-
Ermittlung der WHERE-Klausel mit internen und externen Filtern
-
Laden der Daten aus der Datenbank
-
Anreichern der Entities mit berechneten Spalten
-
Entities im delayed-logic-Modus können mit einer POST-Anfrage verändert oder mit einer DELETE-Anfrage gelöscht werden. Entities in diesem Modus sind zustandslos (stateless) und belegen auf dem Server nach der Abarbeitung einer Anfrage keine Ressourcen mehr.
Unterstützte HTTP-Methoden:
-
Interaktive Entities müssen einmalig mit einer PUT-Anfrage erzeugt werden, und erhalten danach eine eigene ID. Benutzen Sie bei nachfolgenden Anforderungen (POST oder DELETE) diese ID.
Unterstützte HTTP-Methoden:
-
PUT (erzeugen von interaktiven Entities)
-
POST (ändern von interaktiven Entities)
-
DELETE (löschen von interaktiven Entities)
