API para desarrolladores (parte 2)
Como les contamos en el último post, hoy estaremos viendo como usar los servicios que requieren autenticación. Primero, como autenticarte con tu usuario, de esta forma obtener el token de autenticación (JWT), y con el mismo, poder realizar todas las consultas que queramos a estos servicios autenticados.
Documentación de la API para desarrolladores
La especificación de la API se encuentra en: https://api.inbest.today/apidoc/
Servicios con autenticación
Estos servicios de consulta de información de la plataforma Inbest Network, requieren autenticación, al contrario al post anterior, la información que dan estos servicios no es pública. Pero no es solo eso, la información a la que se accede esta destinada al usuario que se encuentra autenticado, o sea, que realizó el login para acceder a la plataforma (Google o Facebook, por el momento).
Por lo tanto, si se utiliza el servicio GET de profile (perfil) se obtiene la información del usuario autenticado, no de cualquier usuario.
Autenticación
Hoy vamos a ver como autenticarnos utilizando la documentación pública. El primer paso es logearse, de la misma forma que lo hacemos en la web o la app, para poder obtener el JWT token, con él vamos a poder realizar las consultas que queramos a los servicios que requieren autenticación.
Antes de seguir, ¿qué es JWT token? Si ya lo sabes, salteate estas líneas. Para los que nunca escucharon nada y, sin entrar en tanto detalle, solo para que sepan de que se trata, JWT = JSON Web Token, es un token en formato JSON que contiene la información de la persona que se autenticó (email, nombre y más datos), pero la misma está encriptada, y permite al sistema saber que alguien está autenticado y saber quien es.
Si quieren saber más de este tema no duden en surfear la web que hay muchísima información. Acá les dejo un link donde podrían empezar, JWT.
Como son muy largos los JWT para pegar acá como para que puedan verlo, prefiero que los generen ustedes mismos y los conozcan de primera mano, en muy poquito ya vas a tener el tuyo.
Ahora sí, vamos a autenticarnos. Accedemos a https://api.inbest.today/apidoc/ desde nuestro browser preferido y vamos a la primer sección que se llama “Sign up / Sign in”, y apretamos en “Example - obtain jwt token”.
Una vez en la pantalla de “Login example”, nos aparecen los dos medios de acceso que se utilizan en todas las plataformas de Inbest Network, Google y Facebook. Utilizamos la opción que más nos guste. En caso de que ya tengan cuenta con Inbest, pueden utilizar esa misma y, al utilizar los servicios más adelante, acceden a la misma información que les aparece en la web o app.
Una vez que se autentiquen, obtendrán como respuesta el JWT correspondiente. Copiar el token para continuar (en la imagen: eyJhbGciO…)
IMPORTANTE: El JWT tiene un tiempo de duración, es necesario renovarlo.
En caso de recibir un mensaje de 403 al utilizar un servicio de la API, código de prohibido (forbidden) en HTTP, indica problemas de autenticación.
Frente a un caso así, regenerar el JWT token que se está utilizando, puede haber vencido. O bien, leer bien la documentación del servicio que se está utilizando por si detalla alguna razón con respecto a mayores permisos necesarios.
Identificar los servicios autenticados
Del gran listado de servicios que tiene la API para desarrolladores, es importante distinguir entre los que requieren autenticación de los que no. Para poder hacerlo, hay que saber que el JWT token que obtuvimos antes se debe agregar en el encabezado (Header) de la consulta, como Authorization.
Por lo tanto, todo servicio que cuenta con la descripción que se muestra en la imagen, denota que requiere agregar el Header Authorization para la consulta y, por lo tanto, requiere autenticación.
Entonces el JWT token se debe agregar sumando “Bearer {token}” (léase, Bearer espacio {token}, donde el token lo copiamos en el paso anterior)
Servicio de prueba: GET de profile
Llamada del servicio
https://api.inbest.today/api/v1/profile
Sumamos el token junto con la palabra Bearer, como ya vimos antes, y presionamos “send”.
Como pueden ver ya pueden acceder a la información del perfil, servicio muy sencillo pero que ejemplifica bien los pasos a seguir.
Servicio de prueba: GET de movimientos
Llamada del servicio
https://api.inbest.today/api/v1/movement?mode=<mode>&limit=<limit>&start_at=<start_at>&status=<status>&transfer_with=<transfer_with>
Parámetros de filtrado
- mode: ‘live’. Actualmente es el único modo habilitado.
- limit: Cantidad máxima de movimientos en la respuesta.
- start_at: El id del movimiento desde el que quiero recibir respuesta.
- status: Filtrar los movimientos según su estado.
- transfer_with: Filtro para obtener las transferencias con un determinado usuarios, se le pasa el uid del usuario particular.
Utilizando los parámetros “limit” y “start_at”, se utilizan para paginar la respuesta del listado de movimientos.
Un detalle antes de presionar send y realizar la consulta, es que la URL que aparece bajo “Send a Sample Request”:
https://api.inbest.today/api/v1/movement?mode=:mode&limit=:limit&start_at=:start_at&status=:status&transfer_with=:transfer_with
Se le deben eliminar los parámetros en caso de no usarlos. Por ejemplo, si queremos no usar ningún parámetro de filtrado la URL que se debe utilizar es https://api.inbest.today/api/v1/movement. Mientras que si se busca solo definir el limite de movimientos sería https://api.inbest.today/api/v1/movement?limit=:limit
Finalmente, apretamos send.
Ejemplo de respuesta:
Estos dos servicios sirven de ejemplo para que se entienda la dinámica de como utilizar la API de desarrolladores. Ahora les toca a ustedes empezar a combinar los distintos servicios para lograr toda la funcionalidad que se aplica tanto en la web, como en las apps.
Pueden dejar sus comentarios por si quieren que veamos en detalle algún otro servicio en particular, y vamos a tratar de armarlo para ustedes. O por cualquier otra consulta que les surja.
