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:

php /var/www/plugin/remote/brandbox/framework/src/entrypoint.php -endpoint=Cron -package=XXX/YYY -host=your.brandbox.de -cronjobid=123

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)

Eventübersicht