Introducción
Conozca la API y aprenda a usarla.
Si aún no sabe qué es, podemos presentarlo diciendo que API es la abreviatura de lo que se conoce como interfaz de programación de aplicaciones. Básicamente una API es un software que actúa como intermediario entre dos aplicaciones. Es un mensajero que ayuda a las aplicaciones a comunicarse entre sí. Esto significa que una aplicación externa a la API consumirá los recursos de esta y trabajará con ellos según el propósito que tenga para su funcionalidad. Esto puede lograrse a través de los formatos XML o JSON.
El uso de esta API está dirigida a la funcionalidad de los requerimientos de Morris y está estructurada en formato JSON. por lo que más adelante encontrará la documentación de cada uno de los endpoints y la funcionalidad que estos proveen.
La api provee varias formas de manipular los datos de cada entidad usando simples parámetros por la url, como filtros, paginación, búsquedas etc. por lo que ya no es necesario incluir un endpoint de búsquedas , de filtros o de condiciones muy específicas tales como los datos que pertenecen a cierto usuario o al usuario actualmente logueado.
todo esto ya es posible manejarlo a nivel global en toda la api únicamente usando parámetros por url. Esto permite seleccionar datos según la necesidad de la consulta usando condicionales "sql". Con esto podemos manipular por url el resultado de la consulta a la api, por lo que podemos usar esta ventaja para crear buscadores por ejemplo. si después de leer esto no entiende la metodología de las consultas no se preocupe el contenido a continuación explica cada una de estas funcionalidades.
Includes
Los includes son una forma de llamar entidades relacionadas con el recurso solicitado. tome como ejemplo una consulta tipo GET que nos devuelve una lista de películas:
axios . request ( {
</script>
normalmente tendremos una respuesta similar a esta:
ahora si agregamos el parámetro include podremos llamar entidades relacionadas de la siguiente manera:
ahora la consulta nos devolverá para cada objeto la propiedad "category" con la información de la categoría:
puedes llamar múltiples includes simplemente separándolos por comas:
también puedes anidar includes, tome como ejemplo que category acepta el include de "status"
podemos llamarlo desde la ruta de movies pidiendo el estado de la categoría de la siguiente manera:
la consulta nos devolverá algo como esto:
puedes ver que includes puedes poner en la documentación de cada endpoint.
Paginación
La paginación es la mejor forma de economizar la carga grande de datos simplemente separándose por lotes. Esto acorta muchísimo los tiempos de carga de las consultas a la api. por defecto cualquier petición a la api no devuelve los datos paginados si no la lista completa. para solicitar una paginación puedes hacerlo pasando los parámetros "top" y "page" ejemplo:
En este caso el parámetro "top" indica el número de datos límite por consulta que en el ejemplo anterior es de "5". y el parámetro "page" indica el lote de datos que se cargará que en este es el el primero "1". por lo cual la consulta anterior nos devolvería los datos del 1 al 5.
la siguiente consulta devolvería datos del 6 al 10:
así sucesivamente...
Filtros
Los filtros son una forma de seleccionar datos que cumplen con una o más condiciones en específico. la api provee una forma de filtrar las consultas de la base de datos usando condicionales SQL únicamente usando la url, para entender esto es importante conocer las condiciones básicas de sql.
esta seria una consulta sql plana consultando los datos de la tabla "movies"
esta es la consulta base que devuelven todos los endpoints tipo GET, un ejemplo de petición a la lista de películas:
axios . request ( {
</script>
Ahora si deseamos filtrar datos podemos hacerlo pasando el parámetro "filter" por la url y especificando las condiciones que debe cumplir la consulta usando las condicionales "like", "=", "!=", ">", "<" a continuación se explica cada una de estas:
Igual que
Para filtrar datos con la condicional "igual que" pasamos el nombre del atributo seguido de ":" y el valor a coincidir, un ejemplo de filtro usando condicional "=":
Aquí filtramos los datos que tengan el id = 1, puedes especificar cualquier atributo del recurso solicitado otro ejemplo con el atributo name:
Diferente de
Para filtrar datos con la condicional "Diferente de" pasamos el nombre del atributo seguido de "!" y el valor a coincidir, un ejemplo de filtro usando condicional "!=":
Aquí filtramos los datos que tengan el id diferente a "1" lo cual nos trae todos excepto el del id "1", puedes especificar cualquier atributo del recurso solicitado otro ejemplo con el atributo name:
Similar a
Muchas veces necesitamos filtrar datos que cumplan no con una condición exacta si no con una similar a los detalles especificados, para filtrar datos con la condicional "Similar a" pasamos el nombre del atributo seguido de "/" y el valor a coincidir, un ejemplo de filtro usando condicional "like":
En este caso la consulta devolverá todos los datos que tienen en el atributo "name" la palabra "movie" ya sea en mayusculas o minusculas, por lo que un ejemplo de respuesta sería el siguiente:
Mayor que e menor que
Para filtrar datos con la condicional "Mayor que" pasamos el nombre del atributo seguido de ">" y el valor a coincidir, un ejemplo de filtro usando condicional ">":
Aquí filtramos los datos donde su id sea mayor a 1, en el caso de menor que sería exactamente igual solo que en vez de ">" pasamos "<" un ejemplo de condicional "<":
Múltiples condicionales con "and" y "or"
Anteriormente hablamos de las condicionales "=", "!=", "like", ">" y "<" pero también sabemos que es muy necesario hacer uso de todas estas en una sola consulta, lo podemos hacer usando separadores "and" u "or", el condicionante "and" se encarga de validar que todas las condiciones pasadas por url se cumplan, mientras que or se encarga de validar que alguna de estas condiciones se cumplan.
para separar las condicionales por "and" podemos hacerlo usando "," y para separarlas por "or" lo hacemos con "|".
un ejemplo de condicionales múltiples usando "and"
En el ejemplo anterior usamos la separación "and" lo cual validará que todas las condicionales se cumplan
en el caso de "or" se validará que al menos una de todas las condiciones pasadas a la url se cumplan, un ejemplo de condicionales múltiples usando "or"
Select
es importante saber que las condiciones "and" y "or" no pueden ir juntas al tiempo por lo que la siguiente consulta no funcionaría:
En estos casos se le dará prioridad a "or", sin embargo podemos usar el parámetro "select" para separar las consultas "or" de las "and" o las "and" de las "or", lo impórtate es saber que nuestra consulta no debe llevar condicionales "and" y "or" mezcladas. sin embargo es obvio que existan casos donde debamos aplicarlas a ambos, en estos casos usamos a "select" como un sobre filtro para "filter" por lo que nuestro filtro anterior quedaría de la siguiente manera
el parámetro "select" actúa como un sobre filtro de "filter" por lo que primero se ejecutara "filter" y a ese resultado lo filtramos con las condicionales enviadas por "select". esto nos sirve para separar las condicionales, obteniendo primero una consulta usando por ejemplo "or" y sobre ese resultado usando "select" para filtrar usando "and" o usando "filter" para filtrar por "and" y "select" para filtrar la consulta de "filter" por "or".
orderBy
El orderBy parámetro se encarga de ordenar la colección de datos de menor a mayor en el caso de números y fechas, y alfabéticamente en el caso de tratarse de una cadena de texto según el atributo pasado en el parámetro ejemplo:
En este caso se ordenará alfabéticamente ya que estamos ordenando los datos por un atributo de tipo string como lo es el nombre, en el caso de tratarse de un entero como por ejemplo el id se ordenarán los datos de mayor a menor según el valor del id:
Normalmente las colecciones de datos devueltas por la api ya están ordenadas de menor a mayor por id, otro ejemplo podría ser la fecha de creación, que en el caso de que el atributo especificado sea de tipo fecha se ordenará igualmente de menor a mayor:
En este ejemplo ordenamos los datos por el atributo 'created_at' que nos ordenará los datos del más viejo al más reciente, siendo el más reciente el último de todos.
Por último es importante saber que puedes combinar el resto de parámetros con orderBy un ejemplo de esto sería un filtro:
En este caso se llaman solo los datos con id menor a 20 y ordenados del más viejo al más reciente.
orderByDesc
Al igual que el parámetro orderBy este sirve para ordenar colecciones de datos devueltas por la api. la única diferencia es que orderByDesc lo hace inversamente, en los casos de atributos con tipo string se ordenarán alfabéticamente pero de la Z a la A, en el caso de enteros se ordenará de mayor a menor siendo el menor el último, y en el caso de fechas se ordenará del más reciente al más viejo siendo el más viejo el último.
Al igual que orderBy puedes combinar otros parámetros con orderByDesc por ejemplo un filtro:
En este caso se llaman solo los datos con id menor a 20 y ordenados del más reciente al más viejo.
Consultas múltitabla
Anteriormente hablamos de los include para llamar entidades relacionadas como ejemplo tomamos a movies llamando su categoría relacionada de esta manera:
con una respuesta como esta:
ok, ya sabemos qué movies está relacionada con categories, que pasa si queremos filtrar las películas de una categoría en específico?
podemos hacerlo con la "foreign key" que normalmente se declara con el nombre de la tabla en singular y seguido de un "_" y un "id". entonces la "fk" en este caso sería "category_id" y nuestro filtro quedaría de la siguiente manera:
ok, pero y si queremos hacer el filtro por el nombre de la categoría?
aquí es donde entran las consultas multitabla. para hacer esto necesitamos especificar el nombre de la tabla relacionada seguido de "." seguido de la propiedad que deseamos usar para el filtro y seguido del valor usado por el filtro.
un ejemplo de consultas multitabla usando un filtro por nombre de categoría
ok, y cómo podemos saber el nombre de la tabla para especificar por la url?
en la documentación se encuentra el esquema de la base de datos en formato pdf solo tienes que dar click en el botón "workbench" o también puedes ver en cada endpoint una lista de tablas relacionadas con el recurso.
Consultas anidadas
También puedes anidar consultas. supongamos que categories tabla está relacionada con statuses tabla, y nuestro filtro a aplicar es: las películas cuyas categorías están en un estado habilitado. nuestro filtro quedaría de la siguiente manera:
puedes anidar tantas tablas como gustes.
First
En ocasiones necesitaremos obtener únicamente un objeto de un modelo especifico. Para esto podemos usar un filtro por id y luego pasar el parámetro “first” para obtener el primer objeto como respuesta en lugar de una colección de datos.
Normalmente usando un filtro como este:
Obtendríamos una respuesta como esta:
Para traer únicamente el objeto en lugar de la colección pasamos el parámetro “first”:
Que nos devolverá el primer registro en un objeto en lugar de una colección de datos. Por lo cual obtendríamos una respuesta como esta:
Registros eliminados
Normalmente tenemos que eliminar registros de la base datos, lo cual puede ser un problema si se trata de información muy delicada en el sistema, por lo que no podríamos recuperar esta información y se daría por perdida. Para solucionar este problema se aplica la eliminación suave que simplemente pondrá el registro en un estado inactivo que lo hará invisible a los ojos de quienes usan el sistema.
Trashed
Para poder visualizar únicamente los registros eliminados lo hacemos pasando el parámetro “trashed” en la url:
All
Ahora para traer todos los datos incluidos registros eliminados y no eliminados lo hacemos pasando el parámetro “all” en la url
Los parámetros filter, select, first etc… pueden combinarse junto con “trashed” y “all”.
Exportar pdf
Existen casos donde podemos exportar una colección de datos en formato pdf, para hacer esto solo necesitamos pasar el parámetro “pdf” en la url:
También podemos filtrar los datos que se cargaran en el pdf combinando el parámetro “pdf” junto con filter, select etc…
Por defecto se visualiza el pdf en el navegador, si lo que deseas es descargarlo de inmediato puedes hacerlo pasando el parámetro "download" en la url:
Exportar excel
También existen casos donde podemos exportar un csv de datos, para hacerlo simplemente pasamos el parámetro “export” a la url
También es posible filtrar los resultados combinado export con filter, select etc…
Filtrando al usuario actual
Normalmente filtramos información del usuario actual, un ejemplo de esto sería una consulta a las películas del usuario logueado, podríamos usar un filtro para esto que quedaría de la siguiente manera:
o también con una consulta multitabla:
Sin embargo el tener que pasar el id del usuario por la url tendríamos que primero obtener la información del usuario usando un endpoint "auth/me" para obtener ese id, ademas de que tendríamos que enviarlo en todas las peticiones y eso nos obliga a hacer un proceso extra para obtener ese id de donde sea que lo hayamos guardado. para evitar esto la api provee una convención para acceder la información del usuario por la url de la siguiente manera:
aquí solamente cambiamos el id plano por "{auth.user.id}" que autománticamente usara el id del usuario logueado, esto no funciona únicamente para el id puedes usarlo con cualquier atributo del usuario por ejemplo el nombre:
forceAll
En ocasiones la API esta configurada con filtros por defecto, un ejemplo podría ser una consulta a la lista de películas cuya fecha de lanzamiento es menor a 1 año, esto significa que el endpoint api/v1/movies siempre nos traerá independientemente del filtro que usemos las películas ya filtradas de esta manera.
Para forzar a la API a devolver todos los datos e ignore el filtro por defecto podemos hacerlo pasando el parámetro forceAll a la url:
Múltiples parámetros
Por último es importante aclarar que puedes hacer uso de todos los parámetros mencionados anteriormente separándolos por "&" y saber que "include" no necesariamente deber ir de primeras. para poner todos los ejemplos juntos tomemos el ejemplo de una consulta de películas cuyas categorías están habilitadas, paginadas por 20 datos , tomamos el lote número 3 e incluimos al usuario y a la categoría en cada uno de los modelos devueltos:
