laravel api handler
v0.7.3
Este paquete auxiliar proporciona funcionalidad para analizar la URL de una solicitud REST-API.
Nota: Esta versión es para Laravel 5. Cuando use Laravel 4, debe usar la versión 0.4.x.
Instale el paquete a través del compositor ejecutando
composer require marcelgwerder/laravel-api-handler
Una vez que el compositor haya terminado, agregue el proveedor de servicios a la matriz providers en app/config/app.php :
MarcelgwerderApiHandlerApiHandlerServiceProvider::class,
Ahora importa la fachada ApiHandler a tus clases:
use Marcelgwerder ApiHandler Facades ApiHandler ; O establezca un alias en app.php :
'ApiHandler' => MarcelgwerderApiHandlerFacadesApiHandler::class,
¡Eso es todo!
Los métodos de relación ahora necesitan una anotación @Relation para demostrar que son métodos de relación y no cualquier otro método (consulte el número 11).
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
} Si pasa una matriz como segundo parámetro a parseSingle , ahora tiene que haber pares columna/valor. Esto nos permite pasar múltiples condiciones como:
ApiHandler :: parseSingle ( $ books , array ( ' id_origin ' => ' Random Bookstore Ltd ' , ' id ' => 1337 )); Para anular la configuración, cree un archivo llamado apihandler.php en la carpeta de configuración de su aplicación.
Consulte el archivo de configuración en la fuente del paquete para ver qué opciones están disponibles.
El análisis de URL actualmente admite:
Se admiten dos tipos de recursos de API: un único objeto y una colección de objetos.
Si maneja una solicitud GET en un recurso que representa un único objeto como, por ejemplo, /api/books/1 , utilice el método parseSingle .
parseSingle($queryBuilder, $identificación, [$queryParams]):
id o un par de columnas/valores de matriz ( array('isbn' => '1234') ) utilizado como identificador único del objeto. ApiHandler :: parseSingle ( $ book , 1 ); Si maneja una solicitud GET en un recurso que representa varios objetos como, por ejemplo, /api/books , utilice el método parseMultiple .
parseMultiple($queryBuilder, $fullTextSearchColumns, [$queryParams]):
ApiHandler :: parseMultiple ( $ book , array ( ' title ' , ' isbn ' , ' description ' )); Tanto parseSingle como parseMultiple devuelven un objeto Result con los siguientes métodos disponibles:
getBuilder(): Devuelve el $queryBuilder original con todas las funciones aplicadas.
getResult(): Devuelve el objeto de resultado devuelto por las funciones get() o first() de Laravel.
getResultOrFail(): Devuelve el objeto de resultado devuelto por la función get() de Laravel si espera varios objetos o firstOrFail() si espera un solo objeto.
getResponse($resultOrFail = false): devuelve un objeto Response de Laravel que incluye el cuerpo, los encabezados y el código de estado HTTP. Si $resultOrFail es verdadero, el método getResultOrFail() se usará internamente en lugar de getResult() .
getHeaders(): devuelve una serie de encabezados preparados.
getMetaProviders(): devuelve una matriz de objetos de metaproveedor. Cada uno de estos objetos proporciona un tipo específico de metadatos a través de su método get() .
limpieza ($ limpieza): si es verdadero, la matriz resultante se limpiará de relaciones agregadas involuntariamente. Estas relaciones se pueden agregar automáticamente si se accede a ellas como propiedades en los descriptores de acceso del modelo. El valor predeterminado global para la limpieza se puede definir usando la opción de configuración cleanup_relations cuyo valor predeterminado es false .
ApiHandler :: parseSingle ( $ books , 42 )-> cleanup ( true )-> getResponse (); Cada parámetro de consulta, excepto las funciones predefinidas _fields , _with , _sort , _limit , _offset , _config y _q , se interpreta como un filtro. Asegúrese de eliminar los parámetros adicionales que no estén destinados al filtrado antes de pasarlos a parseMultiple .
/api/books?title=The Lord of the Rings
Todos los filtros se combinan con un operador AND .
/api/books?title-lk=The Lord*&created_at-min=2014-03-14 12:55:02
El ejemplo anterior daría como resultado el siguiente SQL donde:
WHERE ` title ` LIKE " The Lord% " AND ` created_at ` >= " 2014-03-14 12:55:02 " También es posible utilizar varios valores para un filtro. Varios valores están separados por una tubería | . Se combinan varios valores con OR excepto cuando hay un sufijo -not , en cuyo caso se combinan con AND . Por ejemplo todos los libros con el id 5 o 6:
/api/books?id=5|6
O todos los libros excepto los que tienen id 5 o 6:
/api/books?id-not=5|6
Se podría lograr lo mismo usando el sufijo -in :
/api/books?id-in=5,6
Respectivamente el sufijo not-in :
/api/books?id-not-in=5,6
| Sufijo | Operador | Significado |
|---|---|---|
| -lk | COMO | Igual que el operador SQL LIKE |
| -no-lk | NO ME GUSTA | Igual que el operador SQL NOT LIKE |
| -en | EN | Igual que el operador SQL IN |
| -no-en | NO EN | Igual que el operador SQL NOT IN |
| -min | >= | Mayor o igual a |
| -max | <= | Menor o igual a |
| -calle | < | Más pequeño que |
| -gt | > | Más que |
| -no | != | No igual a |
Dos formas de ordenar, ascendente y descendente. Cada columna que debe ordenarse de forma descendente siempre comienza con - .
/api/books?_sort=-title,created_at
Se admiten dos implementaciones de búsqueda de texto completo. Puede elegir cuál usar cambiando la opción fulltext en el archivo de configuración a default o native .
Nota: Cuando se utiliza un parámetro _q vacío, la búsqueda siempre arrojará un resultado vacío.
Implementación personalizada limitada (predeterminada)
Un texto determinado se divide en palabras clave que luego se buscan en la base de datos. Siempre que existe una de las palabras clave, la fila correspondiente se incluye en el conjunto de resultados.
/api/books?_q=The Lord of the Rings
El ejemplo anterior devuelve cada fila que contiene una de las palabras clave The , Lord , of , the , Rings en una de sus columnas. Las columnas a considerar en la búsqueda de texto completo se pasan a parseMultiple .
Implementación nativa de MySQL
Si su versión de MySQL admite la búsqueda de texto completo para el motor que utiliza, puede utilizar esta búsqueda avanzada en el controlador de API.
Simplemente cambie la opción de configuración fulltext a native y asegúrese de que haya un índice de texto completo adecuado en las columnas que pase a parseMultiple .
Cada resultado también contendrá una columna _score que le permitirá ordenar los resultados según su coincidencia con los términos de búsqueda. P.ej
/api/books?_q=The Lord of the Rings&_sort=-_score
Puede ajustar el nombre de esta columna modificando la configuración fulltext_score_column en el archivo de configuración.
Para definir la cantidad máxima de conjuntos de datos en el resultado, use _limit .
/api/books?_limit=50
Para definir el desplazamiento de los conjuntos de datos en el resultado, utilice _offset .
/api/books?_offset=20&_limit=50
Tenga en cuenta que para utilizar offset siempre debe especificar también un limit . MySQL arroja un error para la definición de desplazamiento sin límite.
El controlador de API también admite relaciones Eloquent. Entonces, si desea obtener todos los libros con sus autores, simplemente agregue los autores al parámetro _with .
/api/books?_with=author
Las relaciones también se pueden anidar:
/api/books?_with=author.awards
Para que esto funcione, debe agregar la anotación @Relation a cada uno de sus métodos de relación, como:
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
} Esto es necesario por razones de seguridad, de modo que sólo se puedan invocar métodos de relación reales utilizando _with .
Nota: Siempre que limite los campos con _fields en combinación con _with . Debajo del capó, los campos se amplían con las claves primarias/externas de la relación. Eloquent necesita las claves de vinculación para obtener modelos relacionados.
Es posible agregar información adicional a una respuesta. Actualmente existen dos tipos de recuentos que se pueden agregar a los encabezados de respuesta.
El total-count que representa el recuento de todos los elementos de un recurso o, para ser más específicos, el recuento de la instancia del generador de consultas pasada originalmente. El filter-count que además tiene en cuenta los filtros. Por ejemplo, pueden resultar útiles para implementar la paginación.
/api/books?id-gt=5&_config=meta-total-count,meta-filter-count
Todos los metacampos se proporcionan en el encabezado de respuesta de forma predeterminada. Se utilizan los siguientes encabezados personalizados:
| configuración | Encabezamiento |
|---|---|
| meta-recuento-total | Recuento metatotal |
| recuento de metafiltros | Recuento de metafiltros |
De forma predeterminada, los metadatos se incluyen en el encabezado de respuesta. Si desea tener todo junto en el cuerpo de la respuesta, puede solicitar el llamado "sobre", ya sea incluyendo response-envelope en el parámetro _config o anulando el config.php predeterminado del paquete.
El sobre tiene la siguiente estructura:
{
"meta" : {
},
"data" : [
]
}
