Jugando con la API de migasfree

Presentación para la MigasCon de abril de 2020. Lamentablemente, no se pudo celebrar por el confinamiento general que hubo en esas fechas.

Transcript

1. Jose Antonio Chavarría (@jact_abcweb) 2020-04-01 JUGANDO CON LA API DE MIGASFREE (extendiendo la aplicaci n) ó Presentación para la MigasCon de abril de 2020. Lamentablemente, no se pudo celebrar por el confinamiento general que hubo en esas fechas.
2. CONCEPTOS PREVIOS
3. DEFINICI N DE API Ó • Normas de comunicación con una aplicación • Normas pensadas para que un programa se comunique con otro Contrato, con documentación, que representa un acuerdo entre las partes: si una de las partes envía una solicitud remota con cierta estructura en particular, esa misma estructura determinará cómo responderá el software de la otra parte.
4. VENTAJAS • Facilita la integración • Ahorra tiempo y costes • Favorece la innovación • Rentabiliza datos • Acceso a los contenidos manteniendo la seguridad y el control Facilita la integración → interfaz de operaciones que proporciona la aplicación (caja negra) Ahorra tiempo y costes → aprovecha código y funcionalidades ya hechos y probados Favorece la innovación → posibilidad de crear productos nuevos alrededor de otros ya existentes Rentabiliza datos → pago por número de llamadas a la API, etc.
5. INCONVENIENTES • Falta de documentación • Múltiples llamadas para acceder a la información necesaria – Paginación – Datos no relacionados • Versiones (ampliaciones) • Tipos de datos de respuesta inconsistentes • Morir de éxito (rendimiento) • Falta de seguridad en los datos Falta de documentación → no todas las APIs suelen estar bien documentadas. Una página web suele tener múltiples llamadas a la API Rest para conseguir datos relacionados. Las llamadas a una API pueden cambiar según la versión de la misma y puede no quedar claro qué llamada corresponde a tal versión. Si hay múltiples llamadas a una API en cada página y ese sitio web empieza a ser muy solicitado, puede colapsar el servidor muy fácilmente. Cuidado con exponer información sensible a través de una API sin tener en cuenta la seguridad.
6. HISTORIA DE MIGASFREE Y LAS APIs
7. LA EDAD DE LA INOCENCIA • migasfree-client (API privada) – Formato extraño (fichero = mensaje + firma) • API pública – get_projects En los principios del proyecto, nos inventamos una especie de API para la comunicación del cliente (aplicación de escritorio) con el servidor. Todas las llamadas iban a parar a una misma URL. El formato de los argumentos tenía un formato inusual y para darle algo de seguridad se hacía un CRC con una clave que enviaba el servidor. Sin embargo, los datos estaban en texto claro. También había una API pública con algunos puntos de entrada, pero que no seguían ningún estándar de API Rest.
8. EL HOMBRE EN BUSCA DE SENTIDO • Año 2016 – REST API experimental – Basada en DRF – Acceso público y con Token • Nuevas posibilidades – migasfree-play – PUA – Integraciones con terceros (migasfree-sdk) Pero en el año 2016, se inició una API REST experimental para proporcionar acceso público y privado (con token) sobre los datos de la interfaz del servidor. Esto abrió un abanico de nuevas posibilidades y de ahí nacieron proyectos como migasfree-play o PUA (Project Upgrade Assistant), así como integraciones con programas de terceros, que podían hacer uso de la API fácilmente a través de migasfree-sdk.
9. ENCUENTROS EN LA 3 FASE ª • JWT para migasfree-client – Mensajes firmados y cifrados – Operaciones atómicas • GraphQL – migasfree-frontend / migasfree-backend Pero todavía quedaba pendiente la comunicación entre los clientes y el servidor. Por eso, se ha desarrollado, para la versión 5 de la suite, un nuevo protocolo basado en JWT (JSON Web Token). De esta forma los mensajes van, al mismo tiempo, firmados y cifrados. Así, incrementamos la seguridad y la privacidad aunque el protocolo de comunicación sea HTTP. También se ha aprovechado para segmentar los mensajes y facilitar el uso de las operaciones. En la versión 5 de la suite migasfree, estamos empezando a jugar con GraphQL (experimentalmente) para mejorar el rendimiento con la idea de hacer menos peticiones para recabar más datos del servidor. Por el momento no se está usando en migasfree-frontend.
10. EXPLOTACI N Ó
11. COMPARATIVA OPERACIONES • Create POST → • Retrieve GET → • Update PUT, PATCH → • Delete DELETE → Relación entre las operaciones de un CRUD y sus equivalencias con los verbos de una API REST.
12. SWAGGER • /docs/ • Autodocumentación • Válido para API REST – Pública – Privada (con Token) Swagger es un conjunto de herramientas de software de código abierto para diseñar, construir, documentar, y utilizar servicios web RESTful. Usamos Swagger en Django para autodocumentar la API REST del servidor (tanto la pública como la privada). Se encuentra disponible en /docs/.
13. DRF • /api-docs/ • Autodocumentación • Válido para API REST – Pública – Privada (con Token) Como usamos Django Rest Framework en nuestro código, también tenemos autodocumentada la API REST en la ruta /api-docs/.
14. CURL $ _SERVER=http://localhost $ _TOKEN=$(curl -X POST \ -H "Content-Type: application/json" \ -d '{"username":"xxx","password":"xxx"}' \ $_SERVER/token-auth/ | jq -r ".token") $ curl -X GET \ -H "Authorization: Token $_TOKEN" \ -H "Content-Type: application/json" \ $_SERVER/api/v1/token/packages/orphan/ \ | jq -c '.[] | select(.name | contains("azl-"))?' Ejemplo de uso de la API REST con cURL. El principal propósito y uso de cURL es automatizar transferencias de archivos o secuencias de operaciones no supervisadas. Es por ejemplo, una herramienta válida para simular las acciones de usuarios en un navegador web.
15. CORE API • coreapi.org $ pip install coreapi-cli $ coreapi get http://localhost/api-docs/ $ coreapi action api v1 public server info create Core API es un modelo de objetos de documento independiente del formato para representar APIs. Existe una herramienta de línea de comandos que puede utilizar para interactuar con las APIs, así como una biblioteca cliente de Python. Aquí, un ejemplo de uso contra la API de migasfree.
16. CORE API EN PYTHON import coreapi # Initialize a client & load the schema document client = coreapi.Client() schema = client.get("http://localhost/api-docs/") # Interact with the API endpoint action = ["api", "v1", "public", "server", "info", "create"] result = client.action(schema, action) Ejemplo de uso de Core API con la librería de Python.
17. PYTHON REQUESTS import requests import json server = 'http://localhost' data = {'username': 'xxx', 'password': 'xxx'} url = '{}/token-auth/'.format(server) response = requests.post(url, data) print(response.json()) token = response.json()['token'] headers = {'Authorization': 'Token {}'.format(token)} url = '{}/api/v1/token/projects/'.format(server) response = requests(url, headers=headers) print(response.json()) Requests es una biblioteca HTTP para el lenguaje de programación Python. El objetivo del proyecto es hacer que las solicitudes HTTP sean más simples y amigables para los humanos. Requests es una de las bibliotecas de Python más populares que no se incluye con Python (todavía).
18. MIGASFREE SDK import datetime from migasfree_client.utils import get_mfc_project, get_hardware_uuid from migasfree_sdk.api import ApiToken server = 'http://localhost' api = ApiToken(server=server, user=user) project_name = get_mfc_project() project_id = api.id("projects", {"name": project_name}) all_systems_id = api.id("attributes", {"prefix": "SET", "value": "ALL SYSTEMS"}) cid = api.id("computers", {"uuid": get_hardware_uuid()}) attribute_cid = api.id("attributes", {"prefix": "CID", "value": cid}) data = { "name": "bluefish_geany", "start_date": datetime.datetime.now().strftime('%Y-%m-%d'), "project": project_id, "packages_to_install": ["bluefish", "geany"], "included_attributes": [all_systems_id, attribute_cid] } deployment_id = api.add("deployments/internal-sources", data) print(deployment_id) Ejemplo de uso de la explotación de la API de migasfree con el proyecto migasfree SDK. Este proyecto nace con la idea de facilitar y simplificar la utilización de la API del servidor migasfree.
19. POSTMAN Otra herramienta que se puede usar para interactuar con APIs es Postman.
20. AXIOS let server = 'http://localhost' let data = {'username': 'xxx', 'password': 'xxx'} const response = await axios.post(`${server}/token-auth/`, data) let token = response.data.token response = await axios .get(`${server}/api/v1/token/computers/`, { headers: { Authorization: `Token ${token}` } }) .catch((error) => { console.log(error) }) console.log(response.data.results) Si quieres atacar la API de migasfree desde JavaScript, una buena alternativa es la librería Axios (https://flaviocopes.com/axios/). Este es un ejemplo de uso.
21. GRAPHQL query projects { allProjects { id name } } query platforms { allPlatforms { id name projectSet { id name slug pms architecture } } } query computers { allComputers { id name ipAddress syncStartDate syncEndDate errorSet { description } } } query errors { allErrors { id description computer { id } } } Estos son dos ejemplos de consultas GraphQL que ya están implantadas en la suite 5 de migasfree. Están disponibles en la ruta /graphql/ del servidor.
22. APPS DERIVADAS DE LA API • migasfree-client • migasfree-play • Project Upgrade Assistant (PUA) • Script de estadísticas • … puede automatizar migraciones del servidor A lo largo de todos estos años, hemos ido explotando la API del servidor a través de diversas aplicaciones. Empezando con el cliente, después le ha seguido migasfree-play. Con posterioridad creamos PUA para uso interno en el Ayuntamiento de Zaragoza. Esta aplicación nos sirve para estudiar a qué sistema operativo se puede migrar un cierto ordenador, basándonos en el software que tiene actualmente y en una serie de restricciones que son diferentes en cada sistema operativo. También tenemos un script para obtener estadísticas de equipos mensualmente. Este script realiza llamadas a la API. Incluso es posible automatizar migraciones del servidor usando la misma API que este proporciona.
23. CONCLUSIONES El buen uso del concepto de API REST nos ha servido estos últimos años para: * Mejorar la seguridad del proyecto (sobre todo la comunicación entre clientes y servidor). * Estandarizar y documentar el uso de las llamadas (DRF, Swagger). * Ampliar el ecosistema de aplicaciones (migasfree- play, migasfree-sdk, migasfree-frontend). * Facilitar la integración con terceros (a través de múltiples herramientas, como cURL, python requests, Core API, Axios, …).
24. Muchas gracias por vuestra atención :) AHORA OS TOCA JUGAR A VOSOTROS www.migasfree.org fun.with@migasfree.org