TYPO3 Plugin:
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 undgzip
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 DateiHTTP_X_AUTHORIZATION
Header, machen Sie etwas damit und geben Sie ein Array mit folgenden Schlüsseln zurück:erfolg => wahr (
oderfalsch).
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. wirdder 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 danachexit()
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 Methodeinitialize()
, die Sie in Ihrem Handler überschreiben können und die vor dem Aufruf vonhandle()
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. Tabellecf_extbase_datamapfactory_datamap
mit out-of-the-box TYPO3-Einstellungen). In diesem Fall müssen Sie Folgendes ausspülen cache manuell.
Installation
-
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
-
Gehen Sie zum Extension Manager und aktivieren Sie die Erweiterung
simple_api
-
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.
Benötigen Sie schnelle Hilfe mit dieser Extension? Unser Team von erfahrenen TYPO3-Entwicklern löst Probleme unkompliziert und zum Stundensatz.
[DependciesAndConflicts]