laravel api handler
v0.7.3
Dieses Hilfspaket bietet Funktionen zum Parsen der URL einer REST-API-Anfrage.
Hinweis: Diese Version ist für Laravel 5. Wenn Sie Laravel 4 verwenden, müssen Sie Version 0.4.x verwenden.
Installieren Sie das Paket über Composer, indem Sie es ausführen
composer require marcelgwerder/laravel-api-handler
Sobald Composer fertig ist, fügen Sie den Dienstanbieter zum providers -Array in app/config/app.php hinzu:
MarcelgwerderApiHandlerApiHandlerServiceProvider::class,
Importieren Sie nun die ApiHandler Fassade in Ihre Klassen:
use Marcelgwerder ApiHandler Facades ApiHandler ; Oder legen Sie einen Alias in app.php fest:
'ApiHandler' => MarcelgwerderApiHandlerFacadesApiHandler::class,
Das ist es!
Beziehungsmethoden benötigen jetzt eine @Relation Annotation, um zu beweisen, dass es sich um Beziehungsmethoden und nicht um andere Methoden handelt (siehe Problem Nr. 11).
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
} Wenn Sie als zweiten Parameter ein Array an parseSingle übergeben, müssen nun Spalten/Wert-Paare vorhanden sein. Dadurch können wir mehrere Bedingungen übergeben, wie zum Beispiel:
ApiHandler :: parseSingle ( $ books , array ( ' id_origin ' => ' Random Bookstore Ltd ' , ' id ' => 1337 )); Um die Konfiguration zu überschreiben, erstellen Sie eine Datei namens apihandler.php im Konfigurationsordner Ihrer App.
Schauen Sie sich die Konfigurationsdatei in der Paketquelle an, um zu sehen, welche Optionen verfügbar sind.
Die URL-Analyse unterstützt derzeit:
Es werden zwei Arten von API-Ressourcen unterstützt: ein einzelnes Objekt und eine Sammlung von Objekten.
Wenn Sie eine GET-Anfrage für eine Ressource bearbeiten, die ein einzelnes Objekt darstellt, wie zum Beispiel /api/books/1 , verwenden Sie die Methode parseSingle .
parseSingle($queryBuilder, $identification, [$queryParams]):
id -Spalte verwendet wird, oder ein Array-Spalten-/Wertpaar(e) ( array('isbn' => '1234') ), das als eindeutige Kennung des Objekts verwendet wird. ApiHandler :: parseSingle ( $ book , 1 ); Wenn Sie eine GET-Anfrage für eine Ressource bearbeiten, die mehrere Objekte darstellt, wie zum Beispiel /api/books , verwenden Sie die Methode parseMultiple .
parseMultiple($queryBuilder, $fullTextSearchColumns, [$queryParams]):
ApiHandler :: parseMultiple ( $ book , array ( ' title ' , ' isbn ' , ' description ' )); Sowohl parseSingle als auch parseMultiple geben ein Result Objekt mit den folgenden verfügbaren Methoden zurück:
getBuilder(): Gibt den ursprünglichen $queryBuilder mit allen darauf angewendeten Funktionen zurück.
getResult(): Gibt das Ergebnisobjekt zurück, das von den Funktionen get() oder first() von Laravel zurückgegeben wird.
getResultOrFail(): Gibt das Ergebnisobjekt zurück, das von get() -Funktion von Laravel zurückgegeben wird, wenn Sie mehrere Objekte erwarten, oder firstOrFail() wenn Sie ein einzelnes Objekt erwarten.
getResponse($resultOrFail = false): Gibt ein Laravel- Response einschließlich Text, Headern und HTTP-Statuscode zurück. Wenn $resultOrFail wahr ist, wird intern die Methode getResultOrFail() anstelle von getResult() verwendet.
getHeaders(): Gibt ein Array vorbereiteter Header zurück.
getMetaProviders(): Gibt ein Array von Meta-Provider-Objekten zurück. Jedes dieser Objekte stellt über seine get() Methode einen bestimmten Typ von Metadaten bereit.
cleanup($cleanup): Wenn true, wird das resultierende Array von unbeabsichtigt hinzugefügten Beziehungen bereinigt. Solche Beziehungen können automatisch hinzugefügt werden, wenn auf sie als Eigenschaften in Modellzugriffsfunktionen zugegriffen wird. Der globale Standardwert für die Bereinigung kann mit der Konfigurationsoption cleanup_relations definiert werden, deren Standardwert false ist.
ApiHandler :: parseSingle ( $ books , 42 )-> cleanup ( true )-> getResponse (); Jeder Abfrageparameter, mit Ausnahme der vordefinierten Funktionen _fields , _with , _sort , _limit , _offset , _config und _q , wird als Filter interpretiert. Stellen Sie sicher, dass Sie zusätzliche Parameter entfernen, die nicht zum Filtern gedacht sind, bevor Sie sie an parseMultiple übergeben.
/api/books?title=The Lord of the Rings
Alle Filter werden mit einem AND Operator verknüpft.
/api/books?title-lk=The Lord*&created_at-min=2014-03-14 12:55:02
Das obige Beispiel würde zu folgendem SQL führen, wobei:
WHERE ` title ` LIKE " The Lord% " AND ` created_at ` >= " 2014-03-14 12:55:02 " Es ist auch möglich, mehrere Werte für einen Filter zu verwenden. Mehrere Werte werden durch einen senkrechten Strich | getrennt . Mehrere Werte werden mit OR kombiniert, es sei denn, es gibt ein -not -Suffix, dann werden sie mit AND kombiniert. Zum Beispiel alle Bücher mit der ID 5 oder 6:
/api/books?id=5|6
Oder alle Bücher außer denen mit der ID 5 oder 6:
/api/books?id-not=5|6
Dasselbe könnte mit dem Suffix -in erreicht werden:
/api/books?id-in=5,6
Jeweils das not-in Suffix:
/api/books?id-not-in=5,6
| Suffix | Operator | Bedeutung |
|---|---|---|
| -lk | WIE | Identisch mit dem SQL- LIKE Operator |
| -nicht-lk | NICHT WIE | Identisch mit dem SQL NOT LIKE -Operator |
| -In | IN | Identisch mit dem SQL IN Operator |
| -nicht-in | NICHT IN | Identisch mit dem SQL NOT IN Operator |
| -min | >= | Größer oder gleich |
| -max | <= | Kleiner oder gleich |
| -st | < | Kleiner als |
| -gt | > | Größer als |
| -nicht | != | Nicht gleich |
Zwei Sortierarten: aufsteigend und absteigend. Jede Spalte, die absteigend sortiert werden soll, beginnt immer mit einem - .
/api/books?_sort=-title,created_at
Es werden zwei Implementierungen der Volltextsuche unterstützt. Sie können auswählen, welche Version Sie verwenden möchten, indem Sie die fulltext in der Konfigurationsdatei entweder auf default oder native ändern.
Hinweis: Bei Verwendung eines leeren _q Parameters gibt die Suche immer ein leeres Ergebnis zurück.
Begrenzte benutzerdefinierte Implementierung (Standard)
Ein vorgegebener Text wird in Schlüsselwörter zerlegt, die dann in der Datenbank durchsucht werden. Immer wenn eines der Schlüsselwörter vorhanden ist, wird die entsprechende Zeile in die Ergebnismenge aufgenommen.
/api/books?_q=The Lord of the Rings
Das obige Beispiel gibt jede Zeile zurück, die eines der Schlüsselwörter The , Lord , of , the , Rings in einer ihrer Spalten enthält. Die bei der Volltextsuche zu berücksichtigenden Spalten werden an parseMultiple übergeben.
Native MySQL-Implementierung
Wenn Ihre MySQL-Version die Volltextsuche für die von Ihnen verwendete Engine unterstützt, können Sie diese erweiterte Suche im API-Handler verwenden.
Ändern Sie einfach die fulltext -Konfigurationsoption auf native und stellen Sie sicher, dass für die Spalten, die Sie an parseMultiple übergeben, ein ordnungsgemäßer Volltextindex vorhanden ist.
Jedes Ergebnis enthält außerdem eine _score -Spalte, mit der Sie die Ergebnisse danach sortieren können, wie gut sie mit den Suchbegriffen übereinstimmen. Z.B
/api/books?_q=The Lord of the Rings&_sort=-_score
Sie können den Namen dieser Spalte anpassen, indem Sie die Einstellung fulltext_score_column in der Konfigurationsdatei ändern.
Um die maximale Anzahl an Datensätzen im Ergebnis zu definieren, verwenden Sie _limit .
/api/books?_limit=50
Um den Offset der Datensätze im Ergebnis zu definieren, verwenden Sie _offset .
/api/books?_offset=20&_limit=50
Beachten Sie, dass Sie zur Verwendung offset immer auch einen limit angeben müssen. MySQL gibt einen Fehler für die Offset-Definition ohne Begrenzung aus.
Der API-Handler unterstützt auch Eloquent-Beziehungen. Wenn Sie also alle Bücher mit ihren Autoren erhalten möchten, fügen Sie einfach die Autoren zum Parameter _with hinzu.
/api/books?_with=author
Beziehungen können auch verschachtelt sein:
/api/books?_with=author.awards
Damit dies funktioniert, müssen Sie jedoch die Annotation @Relation zu jeder Ihrer Beziehungsmethoden hinzufügen, z. B.:
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
} Dies ist aus Sicherheitsgründen notwendig, damit mit _with nur echte Relationsmethoden aufgerufen werden können.
Hinweis: Immer wenn Sie die Felder mit _fields in Kombination mit _with einschränken. Unter der Haube werden die Felder mit den Primär-/Fremdschlüsseln der Relation erweitert. Eloquent benötigt die Verknüpfungsschlüssel, um verwandte Modelle zu erhalten.
Es ist möglich, einer Antwort zusätzliche Informationen hinzuzufügen. Derzeit gibt es zwei Arten von Zählungen, die den Antwortheadern hinzugefügt werden können.
Die total-count , die die Anzahl aller Elemente einer Ressource darstellt, oder genauer gesagt die Anzahl der ursprünglich übergebenen Abfrage-Builder-Instanz. Die filter-count , die zusätzlich Filter berücksichtigt. Sie können beispielsweise nützlich sein, um eine Paginierung zu implementieren.
/api/books?id-gt=5&_config=meta-total-count,meta-filter-count
Alle Metafelder werden standardmäßig im Antwortheader bereitgestellt. Die folgenden benutzerdefinierten Header werden verwendet:
| Konfig | Kopfzeile |
|---|---|
| Meta-Gesamtzahl | Meta-Gesamtanzahl |
| Metafilteranzahl | Meta-Filter-Anzahl |
Standardmäßig sind Metadaten im Antwortheader enthalten. Wenn Sie alles im Antworttext zusammenfassen möchten, können Sie einen sogenannten „Envelope“ anfordern, indem Sie entweder response-envelope in den _config -Parameter einfügen oder die Standard config.php des Pakets überschreiben.
Der Umschlag hat folgenden Aufbau:
{
"meta" : {
},
"data" : [
]
}
