Platform REST API development with Low-Code approach

1 Introduction
2 Preparing the Development Environment
3 Creation of the Message ontology
4 Creating the API Message
5 Testing the API with Swagger
6 API functionality: sending mails
7 Integrating security into our API: authentication
8 Completing API functionality
9 Deploying your API
10 Managing the API lifecycle from the API Portal

Introduction

This article will show the development lifecycle following a Low-Code approach. This approach is characterised by minimising code development by replacing it with building and deploying with visual environments.

Preparing the Development Environment

For the example, a developer will only need access to one instance of Onesait Platform.

Typically this will be the instance of her project. In the example, we will use the Platform CloudLab Environment, which is a free experimentation environment available to any developer.

As a developer, you only have to connect to this environment and create a DEVELOPER account: https://lab.onesaitplatform.com

Creation of the Message ontology

You will have to define the Message ontology with the proposed attributes. This entity will be the one that the API you will create later on, will work with.

The fields to be defined are:

idMessage: uniquely identifies the message.
txtMessage: message content. Initially, plain text.
typeMessage: indicates the type of the message. Initially, we handle MAIL and it is foreseen to eventually extend it to SMS.
fromMessage: sender of the message.
toMessage: to whom the message is addressed. Depending on the type of message, it will be an email, a telephone number, ...
statusMessage: indicates if the message has been sent or is pending to be sent or is in error, it uses the codes ERROR, PENDING, SENT.
sentDate: indicates the date the message was sent, if it has been sent.
errorOnSending: indicates the error that has occurred when sending the message.

To create the ontology, you will go to the menu option DEVELOPMENT>My Ontologies, indicate CREATE and select:

Now, indicate the name and attributes:

The ontology is always created in the same way, no matter the database in which it is persisted. In this case, yuo must configure the ontology to use MongoDB as repository, which is the default repository and the one that the platform provides and makes available in a transparent way.

The resulting ontology will have the following JSON schema:

Once the creation of the ontology is finished, you can able to see it in the list of My Ontologies. The platform has created below the Mongo collection that represents the entity.

More information on how to create an ontology here: https://onesaitplatform.atlassian.net/wiki/spaces/DOCT/pages/3522822145/First+steps+with+Onesait+Platform+CloudLab#Step-2:-Create-an-Entity/Ontology-in-the-Platform

Creating the API Message

Once you have defined the ontology, you can APIfy it.

You can define all the operations you want. By default, the basic CRUD operations are created, but you can create custom operations to, for example, filter data based on a parameter, pagination, etc.

All this can be done with SQL syntax.

The operations you'll want to create are:

Detail of a message.
List of messages, paginated.
List of messages by status.
List of messages destined to a person.
Number of messages by message type (a structure with the type and number of messages).
Number of messages by sender.

The procedure to create each API operation is as simple as this:

You can create queries that group, and you can also add post-processing in JavaScript. For example, if you want to group by statusMessage to group by status, and also give the value in %:

Once you have defined all the operations you will need, you must create the API:

More information about creating APIs here: https://onesaitplatform.atlassian.net/wiki/spaces/DOCT/pages/2220196782

Testing the API with Swagger

When you develop an API in the Platform, you am automatically deploying it on the embedded API Gateway (by default in DEVELOPMENT state).

The platform publishes the API in Open API 3 format, and it also integrates Swagger, so it has an option to test the API operation in a very easy way from the APIs list:

Besides, the platform already integrates security in the REST API, so that when you want to invoke the API, you will have to indicate the OAuth2 token or the X-OP-APIKey token.

More information on how to invoke an API from Swagger here: API Invocation with Swagger and Client Generation with Swagger Editor

API functionality: sending mails

Now it's time to configure the functionality to send emails or SMS every time the API POST operation (new message) is used. To do this, use the Flow Engine tool.

Create a flow that is pending of the insertion notifications on the Message ontology. Then, it will proceed to send the mail, and finally, it will update the status of the Message, contemplating the possible appearance of errors in the sending.

Using the custom boxes provided by the platform, you can develop this flow quickly:

Going into detail of the phases of the flow:

Listen for push notifications on the Message ontology.
Apply a small JavaScript code to format the msg object that is passed to the subsequent boxes.
Depending on the type of Message (MAIL or SMS), bifurcate the flow. For now, we are mocking up the SMS type by sending those to a DEBUG box.
In the following Function box, indicate the properties that you will pass to the onesait platform's mail service: recipient, subject... obtained from the Message notification payload itself.
The mail service sends the mail to the recipient.
If everything went well, the Message is updated to SENT and the date is indicated. On the other hand, if there is an error, the message is updated to ERROR, and the error is indicated in the ontology field.
Depending on what has happened, invoke one endpoint or another of the Message API.

Integrating security into our API: authentication

If you use the platform to create the APIs, they are already secured by default, being able to authenticate via REST, either by X-OP-APIKey header, where you indicate the user's API token, or through an Authentication header, where you indicate the user's Bearer token, generated by the platform's Identity Manager.

NOTE: From the Swagger UI, only the documented X-OP-APIKey header appears. However, from any REST client, for example Postman, you can use any of the two headers.

Completing API functionality

Now, we will configure the SMS sending service. You are going to use Twilio as a messaging service, as it offers $16 free to use its services. So, sign up and set up a number for the trial period.

In this case, you will make use of the REST API it offers. Reading the documentation, you can quickly set up a Swagger descriptor that includes the operation of sending messages:

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

This descriptor can be imported as an API in the platform (see https://onesaitplatform.atlassian.net/wiki/spaces/DOCT/pages/2220828880 ) and then you can invoke it in your Flow Engine flow.

Once published, you can create the box in the flow for invocation.

Remove the box you had from "debug", and replace it with "API Rest invoker", with the following parameters:

The accountSID you have from Twilio:

The Authorization header, which will consist of: 'accountSid:token' encoded in Base 64, adding 'Basic ' before it.
From: it will be the number enabled by Twilio to send SMS during the trial period.
To: take it from the incoming message
Body: take it from the incoming txtMessage.

Now, if you send the following payload to the platform:

  {
    "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"
  }

You will receive a message:

Deploying your API

In the Platform, while you are developing, either publishing an API or creating a Flow in the FlowEngine, what you are developing is automatically being deployed visually, so no additional steps are required.

Managing the API lifecycle from the API Portal

As an API is created from the platform, you can manage its lifecycle as explained here: https://onesaitplatform.atlassian.net/wiki/spaces/DOCT/pages/2220196723