Endpoint – Endpunkte

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

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

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

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