Plataforma de desarrollo API REST con enfoque Low-Code

1 Introducción
2 Preparación del entorno de desarrollo
3 Creación de la ontología Message
4 Creación del API de Message
5 Probando la API con Swagger
6 Funcionalidad API: envío de correos
7 Integrando la seguridad en nuestra API: autenticación
8 Completando la funcionalidad de la API
9 Desplegando tu API
10 Gestionando el ciclo de vida de la API desde el Portal de la API

Introducción

Este artículo mostrará el ciclo de vida del desarrollo siguiendo un enfoque Low-Code. Este enfoque se caracteriza por minimizar el desarrollo de código, reemplazándolo con la construcción e implementación de entornos visuales.

Preparación del entorno de desarrollo

Para el ejemplo, un desarrollador solo necesitará acceso a una instancia de Onesait Platform.

Por lo general, ésta será la instancia de su proyecto. En el ejemplo, utilizaremos Platform CloudLab Environment, que es un entorno de experimentación gratuito disponible para cualquier desarrollador.

Como desarrollador, solo tienes que conectarte a este entorno y crear una cuenta DE DESARROLLADOR: https://lab.onesaitplatform.com

Creación de la ontología Message

Tendrás que definir la ontología Message con los atributos propuestos. Esta entidad será con la que trabajará la API que crearás más adelante.

Los campos a definir son:

idMessage: identifica de forma única el mensaje.
txtMessage: contenido del mensaje. Inicialmente, texto plano.
typeMessage: indica el tipo de mensaje. Inicialmente manejamos MAIL y se prevé eventualmente extenderlo a SMS.
fromMessage: remitente del mensaje.
toMessage: a quién va dirigido el mensaje. Según el tipo de mensaje será un correo electrónico, un número de teléfono, etc.
statusMessage: indica si el mensaje ha sido enviado o está pendiente de ser enviado o es erróneo. Utiliza los códigos ERROR, PENDING, SENT.
sentDate: indica la fecha en que se envió el mensaje, si se ha enviado.
errorOnSending: indica el error que se ha producido al enviar el mensaje.

Para crear la ontología, ve a la opción de menú DESARROLLO>Mis Ontologías, elige CREAR y selecciona:

Ahora, indica el nombre y los atributos:

La ontología siempre se crea de la misma manera, sin importar la base de datos en la que se persiste. En este caso, se debe configurar la ontología para usar MongoDB como repositorio, que es el repositorio por defecto y el que la plataforma proporciona y pone a disposición de forma transparente.

La ontología resultante tendrá el siguiente esquema JSON:

Una vez finalizada la creación de la ontología, podrás visualizarla en la lista de Mis Ontologías. La plataforma ha creado a continuación la colección Mongo que representa a la entidad.

Más información sobre cómo crear una ontología aquí: Primeros Pasos (con Onesait Platform CloudLab)

Creación del API de Message

Una vez que hayas definido la ontología, puedes APIficarla.

Puedes definir todas las operaciones que quieras. De forma predeterminada, se crean las operaciones CRUD básicas, pero puedes crear operaciones personalizadas para, por ejemplo, filtrar datos en función de un parámetro, paginar, etc.

Todo esto se puede hacer con sintaxis SQL.

Las operaciones que querrás crear son:

Detalle de un mensaje.
Lista de mensajes, paginada.
Lista de mensajes por estado.
Lista de mensajes destinados a una persona.
Número de mensajes por tipo de mensaje (una estructura con el tipo y número de mensajes).
Número de mensajes por remitente.

El procedimiento para crear cada operación de API es tan simple como esto:

Puedes crear consultas que agrupen y también puedes agregar procesamiento posterior en JavaScript. Por ejemplo, si deseas agrupar por statusMessage para agrupar por estado y también dar el valor en %:

Una vez que hayas definido todas las operaciones que necesitarás, debes crear la API:

Más información sobre la creación de API aquí: ¿Cómo crear un API REST con una custom query y procesado?

Probando la API con Swagger

Cuando desarrollas una API en la plataforma, la estás implementando automáticamente en la puerta de enlace API integrada (de forma predeterminada en el estado DESARROLLO).

La plataforma publica la API en formato Open API 3, y además integra Swagger, por lo que tienes la opción de probar el funcionamiento de la API de una forma muy sencilla desde la lista de APIs:

Además, la plataforma ya integra seguridad en la API REST, por lo que cuando quieras invocar la API, deberás indicar el token OAuth2 o el token X-OP-APIKey.

Más información sobre cómo invocar una API desde Swagger aquí: Invocación a APIS con Swagger y generación de cliente con Swagger Editor

Funcionalidad API: envío de correos

Ahora es el momento de configurar la funcionalidad para enviar correos electrónicos o SMS cada vez que se utiliza la operación API POST (mensaje nuevo). Para hacer esto, usa la herramienta Flow Engine.

Crea un flujo que esté pendiente de las notificaciones de inserción en la ontología Mensaje. Luego, éste procederá al envío del correo, y finalmente, actualizará el estado del Mensaje, contemplando la posible aparición de errores en el envío.

Usando las cajas personalizadas proporcionadas por la plataforma, puedes desarrollar este flujo rápidamente:

Entrando en detalle de las fases del flujo:

Escucha las notificaciones push en la ontología de mensajes.
Aplica un pequeño código JavaScript para formatear el objeto msg que se pasa a los cuadros posteriores.
Dependiendo del tipo de Mensaje (CORREO o SMS), bifurca el flujo. Por ahora, estamos simulando el tipo de SMS enviándolos a un cuadro DEBUG.
En el siguiente cuadro de Función, indica las propiedades que pasarás al servicio de correo de la plataforma onesait: destinatario, asunto... obtenidas del propio payload de Notificación del Mensaje.
El servicio de correo envía el correo al destinatario.
Si todo salió bien, el Mensaje se actualiza a ENVIADO y se indica la fecha. Por otro lado, si hay un error, el mensaje se actualiza a ERROR y se indica el error en el campo de ontología.
Según lo que haya pasado, se invoca un endpoint u otro de la Message API.

Integrando la seguridad en nuestra API: autenticación

Si usas la plataforma para crear las APIs, éstas ya vienen aseguradas por defecto, pudiendo autenticarse vía REST, ya sea por cabecera X-OP-APIKey, donde indicas el token de la API del usuario, o por cabecera de Autenticación, donde indicas el token Bearer del usuario, generado por el Gestor de Identidad de la plataforma.

NOTA: Desde la interfaz de usuario de Swagger, sólo aparece el encabezado X-OP-APIKey documentado. Sin embargo, desde cualquier cliente REST, por ejemplo Postman, puede utilizar cualquiera de las dos cabeceras.

Completando la funcionalidad de la API

Ahora, configuraremos el servicio de envío de SMS. Vas a usar Twilio como servicio de mensajería, ya que ofrece $16 gratis para usar sus servicios. Así que regístrate y configura un número para el período de prueba.

En este caso, harás uso de la API REST que ofrece. Leyendo la documentación, puedes configurar rápidamente un descriptor de Swagger que incluye la operación de envío de mensajes:

swagger: '2.0'
info:
  description: 'Twilio API descriptor'
  version: 1.0.0
  title: Twilio API REST
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: api.twilio.com
basePath: /2010-04-01
tags:
  - name: SMS
    description: SMS Service
schemes:
  - https
paths:
  '/Accounts/{accountSID}/Messages.json':
    post:
      tags:
        - SMS
      summary: uploads an image
      description: ''
      operationId: sendMessageSMS
      consumes:
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - name: accountSID
          in: path
          description: Twilio Account SID
          required: true
          type: string
        - name: Authorization
          in: header
          description: Basic Authentication
          required: true
          type: string
        - name: From
          in: formData
          description: From phone
          required: true
          type: string
        - name: To
          in: formData
          description: To phone
          required: true
          type: string
        - name: Body
          in: formData
          description: Text body
          required: true
          type: string

      responses:
        '200':
          description: successful operation

Este descriptor se puede importar como una API en la plataforma (consulta Importar datos a una ontología desde fichero vía API ) y después puedes invocarlo en tu flujo de Flow Engine.

Una vez publicado, puedes crear el cuadro en el flujo para la invocación.

Quita la casilla que tenías de "debug", y reemplázala por "API Rest invocador", con los siguientes parámetros:

El accountSID que tienes de Twilio:

El eEcabezado de Autorización, que consistirá en: 'accountSid:token' codificado en Base 64, agregando 'Basic' antes.
De (From): será el número habilitado por Twilio para enviar SMS durante el periodo de prueba.
Para (To): tómalo del mensaje entrante
Cuerpo (Body): tómalo del txtMessage entrante.

Ahora, si envías la siguiente payload a la plataforma:

  {
    "idMessage": "78556-fdg",
    "txtMessage": "Hola esto es una prueba SMS. Irá bien",
    "typeMessage": "SMS",
    "toMessage": "+34616986373",
    "statusMessage": "SENT",
    "sentDate": "2020-05-14T09:29:26.047+0000"
  }

Recibirás un mensaje:

Desplegando tu API

En la plataforma, mientras estás desarrollando, ya sea publicando una API o creando un flujo en FlowEngine, lo que estás desarrollando se implementa automáticamente de forma visual, por lo que no se requieren pasos adicionales.

Gestionando el ciclo de vida de la API desde el Portal de la API

Como se crea una API desde la plataforma, puedes administrar su ciclo de vida como se explica aquí: Ciclo de vida de las APIs

platform-doc-es