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.
   

   View Slide

2. CONCEPTOS PREVIOS
   

   View Slide

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.
   

   View Slide

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.
   

   View Slide

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.
   

   View Slide

6. HISTORIA DE
   MIGASFREE Y LAS APIs
   

   View Slide

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.
   

   View Slide

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.
   

   View Slide

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.
   

   View Slide

10. EXPLOTACI N
    Ó
    

    View Slide

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.
    

    View Slide

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/.
    

    View Slide

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/.
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

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).
    

    View Slide

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.
    

    View Slide

19. POSTMAN
    Otra herramienta que se puede usar para interactuar
    con APIs es Postman.
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

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, …).
    

    View Slide

24. Muchas gracias por vuestra atención :)
    AHORA OS TOCA JUGAR A VOSOTROS
    www.migasfree.org
    fun.with@migasfree.org
    

    View Slide