laravel api handler
v0.7.3
Ce package d'assistance fournit des fonctionnalités permettant d'analyser l'URL d'une requête REST-API.
Remarque : Cette version est destinée à Laravel 5. Lorsque vous utilisez Laravel 4, vous devez utiliser la version 0.4.x.
Installez le package via composer en exécutant
composer require marcelgwerder/laravel-api-handler
Une fois composer terminé, ajoutez le fournisseur de services au tableau providers dans app/config/app.php :
MarcelgwerderApiHandlerApiHandlerServiceProvider::class,
Importez maintenant la façade ApiHandler dans vos classes :
use Marcelgwerder ApiHandler Facades ApiHandler ; Ou définissez un alias dans app.php :
'ApiHandler' => MarcelgwerderApiHandlerFacadesApiHandler::class,
C'est ça!
Les méthodes relationnelles ont désormais besoin d'une annotation @Relation pour prouver qu'il s'agit de méthodes relationnelles et non d'autres méthodes (voir numéro 11).
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
} Si vous transmettez un tableau comme deuxième paramètre à parseSingle , il doit maintenant y avoir des paires colonne/valeur. Cela nous permet de passer plusieurs conditions comme :
ApiHandler :: parseSingle ( $ books , array ( ' id_origin ' => ' Random Bookstore Ltd ' , ' id ' => 1337 )); Pour remplacer la configuration, créez un fichier appelé apihandler.php dans le dossier de configuration de votre application.
Consultez le fichier de configuration dans la source du package pour voir quelles options sont disponibles.
L'analyse d'URL prend actuellement en charge :
Il existe deux types de ressources API prises en charge : un objet unique et une collection d'objets.
Si vous gérez une requête GET sur une ressource représentant un seul objet comme par exemple /api/books/1 , utilisez la méthode parseSingle .
parseSingle($queryBuilder, $identification, [$queryParams]) :
id ou une ou plusieurs paires colonne/valeur du tableau ( array('isbn' => '1234') ) utilisée comme identifiant unique de l'objet. ApiHandler :: parseSingle ( $ book , 1 ); Si vous gérez une requête GET sur une ressource représentant plusieurs objets comme par exemple /api/books , utilisez la méthode parseMultiple .
parseMultiple($queryBuilder, $fullTextSearchColumns, [$queryParams]) :
ApiHandler :: parseMultiple ( $ book , array ( ' title ' , ' isbn ' , ' description ' )); parseSingle et parseMultiple renvoient tous deux un objet Result avec les méthodes suivantes disponibles :
getBuilder() : renvoie le $queryBuilder d'origine avec toutes les fonctions qui lui sont appliquées.
getResult() : renvoie l'objet résultat renvoyé par les fonctions get() ou first() de Laravel.
getResultOrFail() : renvoie l'objet résultat renvoyé par la fonction get() de Laravel si vous attendez plusieurs objets ou firstOrFail() si vous attendez un seul objet.
getResponse($resultOrFail = false) : renvoie un objet Response Laravel comprenant le corps, les en-têtes et le code d'état HTTP. Si $resultOrFail est vrai, la méthode getResultOrFail() sera utilisée en interne à la place de getResult() .
getHeaders() : renvoie un tableau d'en-têtes préparés.
getMetaProviders() : renvoie un tableau d'objets méta-fournisseur. Chacun de ces objets fournit un type spécifique de métadonnées via sa méthode get() .
cleanup ($ cleanup) : si vrai, le tableau résultant sera nettoyé des relations ajoutées involontairement. De telles relations peuvent être automatiquement ajoutées si elles sont accessibles en tant que propriétés dans les accesseurs de modèle. La valeur par défaut globale pour le nettoyage peut être définie à l'aide de l'option de configuration cleanup_relations qui est par défaut false .
ApiHandler :: parseSingle ( $ books , 42 )-> cleanup ( true )-> getResponse (); Chaque paramètre de requête, à l'exception des fonctions prédéfinies _fields , _with , _sort , _limit , _offset , _config et _q , est interprété comme un filtre. Assurez-vous de supprimer les paramètres supplémentaires non destinés au filtrage avant de les transmettre à parseMultiple .
/api/books?title=The Lord of the Rings
Tous les filtres sont combinés avec un opérateur AND .
/api/books?title-lk=The Lord*&created_at-min=2014-03-14 12:55:02
L'exemple ci-dessus donnerait le SQL suivant où :
WHERE ` title ` LIKE " The Lord% " AND ` created_at ` >= " 2014-03-14 12:55:02 " Il est également possible d'utiliser plusieurs valeurs pour un filtre. Plusieurs valeurs sont séparées par un tube | . Plusieurs valeurs sont combinées avec OR sauf lorsqu'il y a un suffixe -not , elles sont alors combinées avec AND . Par exemple tous les livres avec l'identifiant 5 ou 6 :
/api/books?id=5|6
Ou tous les livres sauf ceux avec l'identifiant 5 ou 6 :
/api/books?id-not=5|6
La même chose pourrait être obtenue en utilisant le suffixe -in :
/api/books?id-in=5,6
Respectivement le suffixe not-in :
/api/books?id-not-in=5,6
| Suffixe | Opérateur | Signification |
|---|---|---|
| -lk | COMME | Identique à l'opérateur SQL LIKE |
| -pas-lk | PAS COMME | Identique à l'opérateur SQL NOT LIKE |
| -dans | DANS | Identique à l'opérateur SQL IN |
| -pas-dans | PAS DANS | Identique à l'opérateur SQL NOT IN |
| -min | >= | Supérieur ou égal à |
| -maximum | <= | Inférieur ou égal à |
| -St | < | Plus petit que |
| -gt | > | Plus grand que |
| -pas | != | Pas égal à |
Deux manières de trier, ascendant et décroissant. Chaque colonne qui doit être triée par ordre décroissant commence toujours par un - .
/api/books?_sort=-title,created_at
Deux implémentations de recherche en texte intégral sont prises en charge. Vous pouvez choisir lequel utiliser en modifiant l'option fulltext dans le fichier de configuration par default ou native .
Remarque : lorsque vous utilisez un paramètre _q vide, la recherche renverra toujours un résultat vide.
Implémentation personnalisée limitée (par défaut)
Un texte donné est divisé en mots-clés qui sont ensuite recherchés dans la base de données. Chaque fois qu'un mot-clé existe, la ligne correspondante est incluse dans le jeu de résultats.
/api/books?_q=The Lord of the Rings
L'exemple ci-dessus renvoie chaque ligne contenant l'un des mots-clés The , Lord , of , the , Rings dans l'une de ses colonnes. Les colonnes à prendre en compte dans la recherche en texte intégral sont transmises à parseMultiple .
Implémentation native de MySQL
Si votre version MySQL prend en charge la recherche en texte intégral pour le moteur que vous utilisez, vous pouvez utiliser cette recherche avancée dans le gestionnaire API.
Modifiez simplement l'option de configuration fulltext en native et assurez-vous qu'il existe un index de texte intégral approprié sur les colonnes que vous transmettez à parseMultiple .
Chaque résultat contiendra également une colonne _score qui vous permettra de trier les résultats en fonction de leur correspondance avec les termes de recherche. Par exemple
/api/books?_q=The Lord of the Rings&_sort=-_score
Vous pouvez ajuster le nom de cette colonne en modifiant le paramètre fulltext_score_column dans le fichier de configuration.
Pour définir la quantité maximale d'ensembles de données dans le résultat, utilisez _limit .
/api/books?_limit=50
Pour définir le décalage des ensembles de données dans le résultat, utilisez _offset .
/api/books?_offset=20&_limit=50
Sachez que pour utiliser offset vous devez également toujours spécifier une limit . MySQL génère une erreur pour la définition du décalage sans limite.
Le gestionnaire d'API prend également en charge les relations Eloquent. Donc, si vous souhaitez obtenir tous les livres avec leurs auteurs, ajoutez simplement les auteurs au paramètre _with .
/api/books?_with=author
Les relations peuvent également être imbriquées :
/api/books?_with=author.awards
Pour que cela fonctionne, vous devez ajouter l'annotation @Relation à chacune de vos méthodes de relation, comme :
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
} Ceci est nécessaire pour des raisons de sécurité, afin que seules les méthodes de relation réelles puissent être invoquées en utilisant _with .
Remarque : Chaque fois que vous limitez les champs avec _fields en combinaison avec _with . Sous le capot, les champs sont étendus avec les clés primaires/étrangères de la relation. Eloquent a besoin des clés de liaison pour obtenir les modèles associés.
Il est possible d'ajouter des informations supplémentaires à une réponse. Il existe actuellement deux types de décomptes qui peuvent être ajoutés aux en-têtes de réponse.
Le total-count qui représente le nombre de tous les éléments d'une ressource ou, pour être plus spécifique, le nombre de l'instance du générateur de requêtes initialement transmise. Le filter-count qui prend également en compte les filtres. Ils peuvent par exemple être utiles pour mettre en œuvre la pagination.
/api/books?id-gt=5&_config=meta-total-count,meta-filter-count
Tous les champs méta sont fournis par défaut dans l’en-tête de réponse. Les en-têtes personnalisés suivants sont utilisés :
| Configuration | En-tête |
|---|---|
| méta-compte-total | Méta-Total-Compte |
| nombre de méta-filtres | Compte de méta-filtres |
Par défaut, les métadonnées sont incluses dans l'en-tête de la réponse. Si vous souhaitez que tout soit réuni dans le corps de la réponse, vous pouvez demander une "enveloppe" soit en incluant response-envelope dans le paramètre _config , soit en remplaçant le config.php par défaut du package.
L'enveloppe a la structure suivante :
{
"meta" : {
},
"data" : [
]
}
