API Extractor

Esta aplicación serverles permite consumir un api que sigue estandares REST y guardar la data en un archivo .csv o .json, según se configure, en un bucket de aws s3 especificado en la configuración.

Caracteristicas

• Autenticación por token
• Refresco de token automaticamente
• Parseo de información de JSON a csv
• Permite programar la ejecución o ejecutar manualmente
• Permite seleccionar los campos especificos que se desea extraer
• Soporta paginación en las apis, ya sea por links o por paginas sequenciales
• La data sensible como tokens, client ids, etc, se pueden guardar en aws secrets y referencialos en la configuración del extractor
• Permite aplicar transformaciones a la data
• El extractor tiene api propia para hacer la configuración y ejecución del mismo
• Etc.

Despliegue

El despliegue se hace en una cuenta de AWS, para eso es necesario los siguientes pre-requisitos

• Instalar Serverless framework en la maquina local, el cual es el framework usado para desplegar el proyecto en los ambientes en aws.

• access key id y access secret key de un usuario de AWS IAM con permisos de administrador que será usado por serverless framework para crear la infraestructura vía linea de comandos.

• Configurar los access key del usuario del paso anterior en la maquina local, esto se puede hacer usando el CLI de aws y corriendo el comando: aws configure

• (Opcional o en caso de obtener un error) Configurar variables de entorno del proyecto, para esto copiamos y pegamosel archivo .env.example y lo renombramos a .env, esto lo podemos hacer a mano, o con el siguiente comando (dentro de la carpeta del proyecto):

  cp .env.example .env
  

  luego establecemos los valores como queramos, el primer valor es EVENT_BRIDGE_SCHEDULE el cual por defecto es 0 1 * * ? * y es la expresión cron que indica la ejecución automatica de las extracciones.

  La segunda variable de entorno es DEFAULT_OUTPUT_BUCKET_SUFFIX que por defecto es 1 y es un texto que se pone al final del nombre del bucket por defecto donde se guarda el output de las extracciones, el cual es api-extractor-output-prod y al final del nombre se agregar este suffix. Esto será necesario configurarlo porque el nombre de los bucket deben ser unicos y si el nombre actual ya esta ocupado entonces debemos añadir un sufijo para hacerlo unico, usando esta variable de entorno, el error que arroja el deploy que nos indica esto es el siguiente:

  Error:
  CREATE_FAILED: ExtractorOutputBucket (AWS::S3::Bucket)
  api-extractor-output-prod-1 already exists
  

• (Opcional) Si estamos en Linux o Mac podemos instalar Make usando

    # Linux
    sudo apt install make
  
    # Mac
    brew install make
    
  

Una vez cumplidos los puntos anteriores estamos listo para desplegar, para esto corremos el comando

make deploy

Usando make, o si no queremos instalar make, podemos correr

sls deploy --verbose --stage prod

El anterior comando nos debe dar un output al final como el siguiente:

Stack Outputs:
  ApiExtractorLambdaFunctionQualifiedArn: *******
  ConfigApiLambdaFunctionQualifiedArn: *******
  RootApiKey: 8b189c1d8fadhf8h4nk0fadh3nd8848667
  HttpApiId: ********
  ServerlessDeploymentBucketName: *********
  HttpApiUrl: https://had73had0.us-east-2.amazonaws.com

De todo esto lo que nos insteresa es el HttpApiUrl y el RootApiKey que nos servirán para consumir el api del lambda extractor.

Nota: una vez hecho el depliegue, por seguridad, borre el usuario que creó con permisos de administrador para propositos del despliegue

Destrucción de recursos

En algunos casos será necesario destruir todos los recursos de aws que fueron creados en el deploy, para esto primero tenemos que limpiar el bucket creado para guardar el output de las extracciones api-extractor-output-prod, luego podemos proceder a destruir los recursos con el siguiente comando

Usando make:

make remove

Sin make:

sls remove --stage prod

API

El lamnda api extractor tiene un api para realizar la configuración, ejecutar manualmente y monitorear las ejecuciones del mismo

Colección de Postman

El archivo docs/postman_collection.json dentro de este repo lo podemos importar en Postman. Una vez importado veremos los siguientes endpoints para consumir

Api keys

Para poder hacer uso del api es necesario usar un api key, al realizar el despliegue este nos arroja un api key que pertenece al usuario root llamada RootApiKey, con esta key podemos consumir el api pero es recomendable crear mas api key para cada persona que va a hacer cambios en la configuración del api, ya que el nombre de cada api key queda guardado en el historial de cambios de la configuración, por lo que al tener un api key para cada persona podemos rastrear cada cambio de cada persona.

Para crear, refrescar y borrar api keys usaremos la carpeta

<img width="300px" src='https://github.com/CrissAlvarezH/api-extractor/blob/main/docs/imgs/postman-api-keys.png'/>

Importante: Solo el api key del root puede crear otras api keys y no se puede borrar desde el api

Estas api keys se guardan en un secret de aws el cual es creado en el deploy y tiene el nombre api-extractor-config/prod/apikeys, desde aquí es la unica forma de borrar el api key del root, el resto se pueden borrar desde el api por Postman.

Configuración para el api extractor

La configuración del extractor se hace mediante el api, si usted importó la colección de Postman podrá ver los siguientes endpoints ahí

De los cuales los endpoints que nos sirven para crear, modificar y borrar una configuración para un api extractor son

• List api configs para listar todas las configuraciones existentes
• Retrieve api config para ver una configuracion especificada por el id en los parametros del endpoint
• Create api config para crear una configuración nueva
• Update api config para actualizar pasando el id
• Delete api config para borrar una configuración

Estructura general

{
    "name": "<string>",
    "auth": {
        "refresh_token": {
            "endpoint":  <Endpoint>,
            "response_token_key":  <JsonField>
        },
        "access_token": "<string>"
    },
    "extractions": [
        {...},
        {...},
        {...}
    ]
}

Endpoint

El endpoint es la representació, en la configuración del extractor, de un endpoint en la vida real, con su url y demas parametros como los query_params que son los parametros que van en la url, los headers y el body. El unico campo obligatorio es la url, el resto son opcionales si no se necesitan.

{
    "url": "<string>",
    "query_params": "<json>",
    "headers": "<json>",
    "body": "<json>"
}

Este objeto se usa en el modulo de auth para especificar el endpoint al cual se tiene que apuntar para obtener el refresco del token, y tambien se usa en cada extracción para especificar el endpoint del cual se va a extraer la data

JsonField

Se usa para especificar un campo en un json, cada campo se separa por un punto, por ejemplo, para el json

{
    "user": {
        "name": "Cristian",
        "account": {
            "number": 2334,
            "type": "credit"
        }
    }
}

Para obtener el number del account el user, se usa el JsonField

user.account.number

El cual retornará 2334

Autenticación por tokens

En la configuración se puede especificar el access token que se va a usar en el apartado de auth.access_token y este se puede usar luego en las extracciones usando referencias.

Refresco de token automatico

Si el token tiene algun tiempo limite de uso y luego explira, podemos configurar el refresco del token, para esto debemos introducir la configuración en auth.refresh_token en el cual podemos especificar el endpoit en el cual se realiza el refresh y luego, especificar cual campo de la respuesta de ese endpoint contiene el token renovado, usando el campo auth.refresh_token.response_token_key

Por ejemplo: suponiendo que para renovar un token debo hacer una petición al endpoint

https://accounts.com/oauth/v2/token?refresh_token=afe21e5ac3f9ea12639

Y este responde con:

{
    "mytoken": "fa146b8e6a67366fd991c7d65",
    "api_domain": "https://www.api.com",
    "token_type": "Bearer",
    "expires_in": 3600
}

Para este caso la configuración deberá ser la siguiente

{
    "auth": {
        "endpoint": {
            "url": "https://accounts.com/oauth/v2/",
            "query_params": {
                "refresh_token": "afe21e5ac3f9ea12639"
            }
        },
        "response_token_key": "mytoken"
    }
}

Ejecutar una configuración

Para ejecutar una configuració ya creada manualmente usamos el endpoint

<img width="800px" src='https://github.com/CrissAlvarezH/api-extractor/blob/main/docs/imgs/postman-execute-config.png'/>

En el parametro config_id debemos poner el id de la configuración antes de dar click en send

Una vez enviada, se lanzará el lambda de extracción para ejecutar dicha configuración, el endpoint responderá de inmediato pero el proceso de ejecución tardará segun la configuración del mismo y la cantidad de data que deba extraer.

Logs de ejecución

Para ver los logs del proceso debemos utilizar el siguiente endpoint

Es importante poner el extraction_id el cual no se debe confundir con el id de la configuración, el extraction_id es el id que tiene cada item dentro de el campo extractions dentro de la configuración

Los logs tienen la siguiente estructura:

{
    "extraction_name": "",
    "extraction_id": "",
    "config_name": "",
    "config_id": "",
    "success": "true | false",
    "error": "null | error_message", // error en caso de ocurrir
    "data_inserted_len": "number", // cantidad de data extraida
    "destiny": "", // ruta en s3 del archivo .csv
    "last": "<json>", // ultimo item extraido la
    "created_at": "", // fecha de inserción del log
}

Extracciones

Las extracciones van configuradas en el capo extractions de la configuración del extractor vista en el punto de la estructura general. Cada extracción tiene la siguiente estructura