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 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. de esta manera podemos solicitar datos que cumplen con ciertas condiciones usando una unica ruta.
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:
Like
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 like 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 <:
Mayor e igual, Menor e igual
Para el caso de mayor e igual que. podemos filtrar usando el operador >= ejemplo:
Esto filtrará los datos cuyo id sea mayor o igual a 10, para el caso de menor e igual que. podemos realizar el filtro usando el operador <= ejemplo:
Esto filtrará los datos cuyo id sea menor o igual a 10.
In
Use la condicional in par filtrar datos que se encuentren en un rango de valores, por ejemplo el siguiente filtro trae solo los datos cuyo id es igual a 1,2,3,4 o 5:
En este caso se usa el - para separar los valores, no se usa , y aque la coma tiene otra funcionalidad asignada. puede usar cualquier atributo de la entidad otro ejemplo con el nombre:
Múltiples condicionales con "and" y "or"
Anteriormente hablamos de las condicionales =, !=, like, >, <, <=, => y in 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 este caso solo traerá los datos cuyo id sea mayor a 0 y menor a 100.
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
En este caso solo traerá los datos cuyo id sea mayor a cero o menor a 100 o diferente a 200 o que en el nombre se encuentre la palabra movie.
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:
Esto se debe a la separación de paréntesis que hay en sql. tome este select como un select * from (select * from ....) es decir un filtro aplicado sobre una constula anterior.
En este caso el parámetro select aplica el filtro sobre el resultado que devuelve filter, entonces podemos usar el parámetro select para seperar las condicionales por ejemplo aplicando en filter las condicionales con or y en select las condicionales con and o viceversa ejemplo:
order_by
El order_by 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 order_by 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.
order_by_desc
Al igual que el parámetro order_by este sirve para ordenar colecciones de datos devueltas por la api. la única diferencia es que order_by_desc 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 order_by puedes combinar otros parámetros con order_by_desc 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:
Los includes agregan una entidad relacionada con la entidad actual al objeto de respuesta, pero también podemos usar el objeto de respuesta para aplicar filtros.
Por ejemplo en este caso cada objeto trae una propiedad category podemos filtrar los datos haciendo uso de esta propiedad de la siguiente manera:
En este caso como el objeto category nos trae un propiedad id y una proipiedad name también podemos filtrar los datos por el nombre de la categoría de esta manera:
Ten en cuenta de que no es necesario que llames el include para que el filtro funcione, si no llamas el include el filtro de igual forma funcionará pero include en estos casos te puede ayudar como guía de como realizar el filtro anidado.
Por ultimo debes saber que los filtros anidados puedes realizarlos con cualquier operador mencionado anteriormente como =, !, >, <, <=, >= like, in etc ... un ejmplo mas aplicando otro operador por ejemplo el in:
Consultas anidadas
También puedes anidar consultas al igual que con los includes, supongamos que categories tabla está relacionada con states tabla atravez de un state_id en ese caso podemos anidar el include para traer el estado de la categoría de esta manera:
Obteniendo una respuesta como está:
Por lo tanto podemos aplicar un filtro por ejemplo por id de estado de categoría de esta manera:
O aplicando el filtro por nombre de estado:
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.
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:
