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.
namespace Brandbox\Framework\Brandbox\Endpoint { use Brandbox\Framework\Brandbox\Http; class YourEndpoint extends EndpointAbstract implements EndpointInterface { use Http\HttpTrait; public const ENDPOINT_NAME = 'public'; protected const IS_SUPER_AUTHORIZED = false; private const CONFIGURE_FLAGS = [ 'client', 'domain', 'language', 'country', 'collation', 'user', 'properties', 'buildTimestamp' ]; public function build() { $this->updateComposerClassLoader(); $this->registerShutdownFunction(); $this->configRuntimeLog(); $this->connectDoctrine(); $this->startSession(); $this->context(self::ENDPOINT_NAME); $this->initialize(self::ENDPOINT_NAME, self::CONFIGURE_FLAGS, false, true, true); $this->basicAuth(); $path = $this->httpGetString('path'); $request = $this->httpGetString('request'); $this->execute(); $this->deliver($request); } } }
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. |
RoleScoped | Gibt an, ob ein Enpoint für Rollen zugeordnet werden kann. Falls nicht, erbt der Endpoint ggf. die Rollen von einem anderen Endpoint. |
Requestable | 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 |