simple_api

Einfache API für TYPO3

Dienst zum Weiterleiten von HTTP/REST-Anfragen an Ihre eigenen Controller.

HINWEIS: Diese Erweiterung wird voraussichtlich von TYPO3-Entwicklern genutzt und dient als zentrale Anlaufstelle für Anfragen an folgende Stellen ihre eigene Geschäftslogik.

Merkmale

• Unterstützung für authentifizierte Methodenaufrufe
• Unterstützung für lokalisierte Anrufe (unter Berücksichtigung der Sprache)
• Unterstützung von Cache-Calls und transparenter Zugriff auf das TYPO3-Caching-Framework in Ihrem API-Handler
• Unterstützung für gzip-Payload, wenn der Header HTTP_ACCEPT_ENCODING vorhanden ist und gzip enthält
• Unterstützung für die dynamische Generierung einer Dokumentation Ihrer API

Darüber hinaus unterstützt dies die Abhängigkeitsinjektion für Ihre API-Handler, Sie müssen nur @inject oder Methoden verwenden vorangestellt durch inject, wie es bei der Programmierung mit Extbase bekannt ist.

Unterschied zu EXT:routing

Im Gegensatz zu EXT:routing erzwingt diese Erweiterung nicht, dass Sie Extbase zuordnen müssen controller/Aktionen auf Routensegmente, sondern lässt Sie stattdessen grundsätzlich ein "Segment" (typischerweise das erste) registrieren und dann wird die gesamte Anforderung einfach an eine handle()-Methode in Ihrem Controller weitergeleitet.

Registrierung von Handlern

Zuerst sollten Sie eine Abhängigkeit in Ihrer Konfigurationsdatei ext_emconf.php hinzufügen, entweder als echte Einschränkung, oder als Vorschlag, je nachdem, was Sie bevorzugen:

$EM_CONF[$_EXTKEY] = [
    / / snip
    Einschränkungen' => [ [
        abhängig' => [ [
            'php' => '5.5.0-7.1.99',
            typo3' => '7.6.0-8.99.99.99',
        ],
        Konflikte' => [],
        "schlägt vor" => [ [
            simple_api' => '',
        ],
    ],
];

Dann, innerhalb von ext_localconf.php:

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['simple_api']['apiHandlers'][] = [
    'route' => '/some-route',
    class' => \VENDOR\YourExt\Api\YourClass::class,
];

sie können ein Muster anstelle einer festen Route registrieren:

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['simple_api']['apiPatternHandlers'][] = [
    'route' => '/members/\d+/history',
    class' => \VENDOR\YourExt\Api\YourClass::class,
];

Dein Handler muss den \Causal\SimpleApi\Controller\AbstractHandler erweitern.

Handlerschlüssel

Das Registrierungsarray unterstützt verschiedene Schlüssel:

• route[obligatorisch]: Der Weg zur Registrierung.

• klasse[obligatorisch]: Die Klasse, die Anfragen an die entsprechende Route bearbeitet.

• contentType[optional]: Inhaltsart der Nutzlast, die von einer POST-Anfrage akzeptiert wird, wird sie automatisch dekodiert bevor Sie Ihren Handler aufrufen.

• methoden[optional]: Die kommagetrennte Liste der vom Handler akzeptierten HTTP-Methoden (z.B. "POST"). Standardwert ist keine Einschränkungen.

• eingeschränkt[optional]: Ob der API-Aufruf einen authentifizierten Aufruf erwartet (über HTTP_X_AUTHORIZATION-Header). Wenn Sie den Zugriff auf einen Teil Ihrer API einschränken, müssen Sie eine Route mit dem Namen /authenticate registrieren, die die Datei HTTP_X_AUTHORIZATION Header, machen Sie etwas damit und geben Sie ein Array mit folgenden Schlüsseln zurück:

  • erfolg => wahr (oder falsch). Wird als _authentifiziertes boolesches Flag an den API-Handler übergeben
  • Benutzerdefinierte Schlüssel werden mit _ vorangestellt und so wie sie sind an den API-Handler übergeben (z.B. wird der Benutzer zu _user)
  • Die Demo des benutzerdefinierten Booleschen Flags kann verwendet werden, um anzugeben, dass die Authentifizierung erfolgreich war, jedoch mit "demonstration". fähigkeiten. Dies muss dann in Ihrem API-Controller behandelt werden, indem Sie wie erwartet den booleschen Flag-Parameter überprüfen _demo.

  Hinweis: Wenn der Header HTTP_X_AUTHORIZATION vorhanden ist, findet die Authentifizierung statt und Ihr Handler wird wie folgt aussehen unabhängig vom Ergebnis des Aufrufs aufgerufen, wenn Sie Ihren Handler nicht explizit als "eingeschränkt" gekennzeichnet haben.

• veraltet[optional]: Boolesches Flag, um die entsprechende Route als veraltet in der Dokumentation zu kennzeichnen.

Nutzlast

Folgende Regeln gelten für die Payload, die Sie von Ihrem API-Handler zurückgeben:

• Die Nutzlast wird als Array erwartet und als inhaltsorientierte Anwendung / json zurückgegeben. Wenn du zurückkehren möchtest einen anderen Inhaltstyp (z.B. ein Bild), sollten Sie dies in Ihrem eigenen API-Handler tun und danach exit() aufrufen.
• Wenn eine Ausnahme ausgelöst wird, wird sie abgefangen und in einen HTTP 500-Fehler gekapselt. Die einzige Ausnahme ist, wenn die Ausnahme \Causal\SimpleApi\Exception\ForbiddenException wird geworfen, es wird stattdessen ein HTTP 403 Fehler ausgelöst.
• Wenn keine Handler gefunden werden, wird ein HTTP 404-Fehler zurückgegeben.

Bekannte Probleme und Workaround

• Extbase Repositories können innerhalb Ihrer API-Handler verwendet werden, aber Sie müssen die Methode includeTCA() manuell aufrufen die Basisklasse, damit das Extbase Mapping für zurückgegebene Objekte verfügbar ist. Dieser Aufruf sollte typischerweise sein teil der Methode initialize(), die Sie in Ihrem Handler überschreiben können und die vor dem Aufruf von handle() aufgerufen wird.

  WARNUNG: Wenn Sie den TCA Ihres Domänenmodells nicht ordnungsgemäß einbinden, können Sie den Extbase Datamap-Cache beschädigen, indem Sie Folgendes tun speichern unvollständiger Mapping-Definitionen im Cache Backend für extbase_datamapfactory_datamap (z.B. Tabelle cf_extbase_datamapfactory_datamap mit out-of-the-box TYPO3-Einstellungen). In diesem Fall müssen Sie Folgendes ausspülen cache manuell.

Installation

1. Klonen Sie dieses Repository in typo3conf/ext/simple_api:

   cd /pfad/zu/typo3conf/ext/
   git clone https://github.com/xperseguers/t3ext-simple_api.git simple_api

   Alternativ können Sie es auch über composer laden:

   composer erfordert kausal/simple_api

2. Gehen Sie zum Extension Manager und aktivieren Sie die Erweiterung simple_api

3. Füge eine Umschreibungsregel zu deinem .htaccess hinzu. Z.B...,

   RewriteRule ^api/(.*)$ /index.php?eID=simple_api&route= [QSA,L]

   oder, wenn Sie Nginx verwenden:

   ^/api/(.*)$ /index.php?eID=simple_api&route= zuletzt umschreiben;

   Dies hat den Effekt, dass diese Erweiterung für die Behandlung von Anfragen verwendet wird, die mit api/ beginnen.

Hinweis: Wenn Sie die Lokalisierung unterstützen müssen (&L=<some-language-uid>), dann sollten Sie das vorgeschlagene Routing ändern oben, um die root page uid Ihrer Website einzuschließen (&id=<some-uid>). Dies ist notwendig, da der Lokalisierungsmodus und die die Standardsprache kann sich in komplexen Umgebungen unterscheiden und kann daher nicht abgeleitet werden.