Eine API (Programmierschnittstelle) ermöglicht die Kommunikation zwischen zwei Systemen. Eine API liefert im Wesentlichen die Sprache und den Vertrag für die Interaktion zweier Systeme. Jede API verfügt über eine Dokumentation und Spezifikationen, die festlegen, wie Informationen übertragen werden können. Genau wie eine Webseite gerendert wird, können APIs HTTP-Anfragen verwenden, um Informationen von einer Webanwendung oder einem Webserver zu erhalten.
Was ist ein Endpunkt?
Einfach ausgedrückt: Ein Endpunkt ist das Ende eines Kommunikationskanals. Wenn eine API mit einem anderen System interagiert, gelten die Berührungspunkte dieser Kommunikation als Endpunkte. Für APIs kann ein Endpunkt etwa die URL eines Servers oder eines Service sein. Jeder Endpunkt ist der Ort, von dem aus APIs auf die Ressourcen zugreifen können, die sie für die Ausführung ihrer Funktion benötigen. Brandbox bietet folgende Standard-Endpunkte an:
Name | Beschreibung |
|---|---|
AdminEndpoint | Erreichbar über /admin |
PublicEndpoint | Erreichbar über alle Pfade außer über Pfade die durch andere Endpunkte reserviert wurden (bspw. /admin). |
InstallEndpoint | Erreichbar über /install |
ErrorDocumentEndpoint | Erreichbar über /errorDocument |
Klassenname | Beschreibung |
OnInitiateEndpoint | Wird hauptsächlich im PublicEndpoint vor dem Verarbeiten der Executes/Requests ausgelöst |
OnPopulateEndpoint | Wird ausgeführt, bevor der Endpoint instanziiert ist - Das Event wird verwendet, um den richtigen Endpoint einzufangen |
OnRequestEndpoint | Wird hauptsächlich im PublicEndpoint ausgelöst - sobald der Parameter $request nicht in der Anfrage steckt |
OnTearDown | Das Event wird ausgelöst, unmittelbar bevor die Antwort gesendet wird |
Aufbau
Es können beliebig neue Endpunkte erstellt werden. Damit sie als solche erkannt werden, müssen sie das Interace \Brandbox\Framework\Brandbox\Endpoint\EndpointInterface implementieren und in einem Package unter Lib/Endpoint als (.*)Endpoint.php liegen. Folgend ein typischer Endpoint.
...
Aus folgenden Gründen kann es notwendig sein einen neuen Endpoint bereitzustellen:
Rollen/Rechte sollen nicht validiert werden (IS_SUPER_AUTHORIZED=true)
Rollen/Rechte oder Basic Auth sollen zu anderen Endpunkten abgegrenzt werden können
Die Standard-Endpoints führen zu viele Operationen aus, die hier nicht benötigt werden
Es wird keine Session benötigt
Es wird keine Datenbank-Verbindung benötigt
Dynamische Executes und/oder Requests sind nicht gewünscht (Sicherheitsaspekt)
Collations/Sprache/Land sollen statisch sein
Die Kopplung an das Mandantensystem soll aufgelöst werden
Der Zugriffsvektor ist ein anderer (bspw. Bash oder Browser)
Events sollen oder sollen nicht getriggert werden (siehe Eventübersicht)
Flags
Endpoints können Flags erhalten, die es möglich machen, sie entsprechend zu klassifizieren. Folgende Flags gibt es:
Klassenname | Beschreibung |
|---|---|
SuperAuthorized | Gibt an, ob ein Endpoint vollständig ohne Rechteprüfung arbeiten kann. |
RoleAssignable | Gibt an, ob ein Enpoint für Rollen zugeordnet werden kann. Falls nicht, erbt der Endpoint ggf. die Rollen von einem anderen Endpoint. |
RoutingExecutable | Gibt an, ob ein Endpoint dynamisch mit Requests erreicht werden kann. Siehe Routing |
RoutingRequestable | Gibt an, ob ein Endpoint dynamisch mit Requests erreicht werden kann. Siehe Routing |
Eventübersicht
Klassenname | Beschreibung |
|---|---|
OnInitiateEndpoint | Wird hauptsächlich im PublicEndpoint vor dem Verarbeiten der Executes/Requests ausgelöst |
OnPopulateEndpoint | Wird ausgeführt, bevor der Endpoint instanziiert ist - Das Event wird verwendet, um den richtigen Endpoint einzufangen |
OnRequestEndpoint | Wird hauptsächlich im PublicEndpoint ausgelöst - sobald der Parameter $request nicht in der Anfrage steckt |
OnTearDown | Das Event wird ausgelöst, unmittelbar bevor die Antwort gesendet wird |