Building Your Own REST API-based AWS Connector

Developers can easily utilize existing connectors or build new ones that integrate AWS services with other applications and systems using Mendix’s efficient low-code development platform.

“AWS recognizes the transformative power of the Mendix platform, and we recognize the transformative power of AWS Services,” says Tim Srock, CEO of Mendix. Because of the successful seven-year strategic relationship between Mendix and AWS, the two companies have decided on an expanded go-to-market relationship.

To learn more about our partnership with AWS, read our press release here. 

Using AWS allows Mendix users to leverage the power of automated procedures and services that AWS provides without having to develop them themselves, saving time and effort. With an AWS connector for Mendix, you can easily tap into the vast number of services available within AWS in a low-code and low-effort way. Making an AWS connector in Mendix can help you streamline your operations and boost your organization’s overall productivity, whether you are developing a custom app that needs to access AWS resources or trying to automate business processes with AWS tools like Lambda and S3. To help you get started with integrating AWS services into your applications right away, I will walk you through the stages of creating a REST API-based AWS connector in Mendix.

Getting Started

When someone discovers that the AWS service which they want to use does not have an existing connector in the Mendix Marketplace, their first reaction is usually something like, “Okay, then that means this solution cannot currently be built with Mendix,” or, “I’m going to have to find a workaround for this.”

I am part of the AWS team in Mendix right now, but before I started, this was also my first reaction. Even after I started, when I already knew that building AWS connectors was the goal of my team, I still felt overwhelmed. I remember thinking: “There are too many AWS services and too many actions for each of them. How are we going to keep up with the demand?” Mind you, this was my thought when I had just begun in the team and when I still thought that building a connector was akin to saving the world — that is to say, that it was extremely hard! But it is not like that at all – building an AWS connector is something all our Mendix developers can do with a little help from our How-To guides!

If you have decided that you need to build a new AWS connector as fast as possible, you might have done a search to see how you could start your journey. There you might have seen that there are two integration methods available to build an AWS connector in Mendix, that is, a representational state transfer (REST) application programming interface (API) or a software development kit (SDK). If you do not have a programming background, simply reading the word SDK may have given you chills. In truth, the process is not as complicated as people (me included) picture it in their heads and is completely doable. But since we are Mendix developers, why not use something we are already familiar with and build a REST API-based AWS connector? Are you up for it?

Here’s a step-by-step guide by yours truly.

Building a REST API-based AWS Connector

The first thing you need to know is that not all AWS services and actions have APIs. This means that before you get started on a REST API-based AWS connector, you need to check if the service and actions you need have APIs available and find the needed HTTP header (their x-amz-target value). If they do not have an API for the service and actions you need, unfortunately, the only other way to continue is to start building a connector using SDK.

For some services and actions, the APIs can be found in the developer guide of the respective AWS service (e.g., Using Signature Version 4 with Amazon Translate – Amazon Translate). However, for others, it is a harder search. A website that I have found useful is AnyAPI (any-api.com). You can go to the Search APIs area, search the name of the AWS service you want to work on, click on it, and find a list of the service’s actions that have APIs, along with their x-amz-target value if it exists.

What we will be implementing comes from our Build an AWS Connector article and its associated links. For more detailed explanations on some of the topics, you can refer to the article as well.
In this scenario, we are assuming that the Amazon Translate Connector does not exist in the Marketplace, but it is a connector we need for a customer project. We have decided to build an AWS connector to use some of its actions (that have APIs) and will implement the TranslateText action.

Initiating the Project

To start working on a connector, we first need to prepare the right environment.

In Mendix Studio Pro, we will create a new module called AmazonTranslateConnector.

Then install and configure the AWS Authentication connector version 2.1 or higher as it is needed to authenticate with Amazon Web services.

In the AmazonTranslateConnector module, impose a folder structure as shown below.

After the working environment is ready, it is time to learn more about the action that we want to implement, especially about what the REST API would need as its request and what we would receive as its response.

To learn more about the action we would like to implement, we can go to the AWS Documentation (amazon.com).

There we find the documentation of the AWS service we are currently working on, which in our case would be the Amazon Translate Documentation.

Here are two guides that are helpful during the development of an AWS connector. Because we are building a REST API-based connector, we choose Amazon Translate API Reference – Amazon Translate API Reference, and then open TranslateText – Amazon Translate API Reference.

On this page, we can find a lot of valuable information about the action we wish to implement, like the request and response syntax, the details of their parameters, as well as common errors that we might face.

After reading more about the action we are going to implement, we will use the response syntax of the TranslateText action to model the response entities.

In the JSON Snippets folder, we create a JSON structure document named after the AWS service, in this case, JSON_TranslateText.

We open the document and paste the response syntax found in TranslateText – Amazon Translate API Reference.

We then click Format. Because we do not care about the applied settings and applied terminologies in our case, we are going to delete those parts and just leave SourceLanguageCode, TargetLanguageCode, and TranslatedText before clicking Refresh and OK.

In the Import Mappings folder, we create an Import Mapping document, name it IMM_TranslateText and click OK.

We open the IMM_ListLanguages document. In the Schema source section, we select JSON structure, and then select the JSON_ListLanguages document.

Then we click Expand all, select Check all, and then OK.

Mendix Studio Pro will now show a visual representation of the mapping of the AWS service into your Mendix application. In some cases, entities that serve no purpose might be generated. Remove them by opening the import mapping document again and unchecking the unnecessary ones. In this case, because there are no unnecessary entities created, we will move on.

After this is done, we click Map automatically. Mendix Studio Pro will create the entities into which the AWS service response will be mapped in the domain model. In our case, the import mapping looks like this:

Now, we go to our domain model and change the names of the created entities to correspond with the TranslateText action.

After our domain model is ready, we can move on to creating our microflow action. However, before we start working on that, we will quickly add the constants we will need later for the AWS authentication.

In the Constants folder under Connection Details, we add the constants as shown in the image below.

Now, we can start working on our microflow.

In the Operations folder, we create a microflow called POST_TranslateText, according to the Mendix naming conventions.

According to TranslateText – Amazon Translate API Reference, the request for this action has three required parameters: SourceLanguageCode, TargetLanguageCode, and Text, which is the text we would like to translate. So, we add three input parameters to the microflow for these parameters and create a string variable called RequestBody to prepare the action request.

We add either the GetSessionCredentials or the GetStaticCredentials Java action from the AWS Authentication module to get our credentials. In this implementation, we will use static credentials, so we add the GetStaticCredentials Java action to our microflow and then add as input parameters the constants AccessKeyID and SecretAccesKey we previously created. The action returns a Credentials object.

We now have both our request and our AWS credentials. However, before we can call the REST service, we need to use Signature Version 4 to add the authentication information to our request call. We need to configure the microflow to get a SigV4Header object by using the Get SigV4 Headers Java action from the AWS Authentication module. For this, we first create a new SigV4Builder object called NewSigV4Builder and fill out its members.

Next, we create a list of SigV4Parameter objects called HeaderList because there are two important headers that are needed as the input parameter of the Get SigV4 Headers Java action.

For the first header, we create a SigV4Parameter object ContentTypeHeader with the following parameters:

• Key – Content-type
• Value – application/x-amz-json-1.1

For the second header, we create a SigV4Parameter object TranslateTextActionHeader to add the x-amz-target for the TranslateText action that we had found before we started working on the connector.

• Key – x-amz-target
• Value – AWSShineFrontendService_20170701.TranslateText

We add both these headers to the HeaderList we have created.

Now, we can add the Get SigV4 Headers Java action to our microflow and use our credentials, the NewSigV4Builder object, and the list of SigV4Parameter objects HeaderList as its input parameters. It returns a SigV4Headers object.

We can now call the REST service, as we have all the needed information. We add a call REST action to the microflow. Location is the EndpointURL attribute of the returned SigV4Headers, Timeout is the Timeout constant created in a previous step, and Request is the RequestBody string variable of the microflow. We add the ContentTypeHeader, TranslateTextActionHeader, and the headers in the returned SigV4Headers object as Custom HTTP Headers to the REST call as well.

We map the Response using the IMM_TranslateText document, which returns a TranslateTextResponse object.

Our completed microflow looks like this:

And we are done! You have created a new Amazon Translate Connector, which can translate text to another language!