Forem: MuleSoft

How to create a proxy SMS API with security policies using Twilio and MuleSoft

Jordan Schuetz — Tue, 11 Aug 2020 18:24:50 +0000

In this tutorial, we are going to build out our API Spec using a Library, Security Scheme, and DataType in API Designer. This API will integrate directly with Twilio and will allow you to send an SMS to a phone number by simply passing a simple POST request with your desired Message and ToPhoneNumber. In Anypoint Studio, we will build out the integration with our Twilio Client ID and Secret which will NOT be exposed to the API Consumer. This means that users interacting with our API only need to be issued a client ID and client secret from our API and can then send text messages without needing to expose our private credentials.

First, log into Anypoint Platform, and go to the Design Center. Click on the Create New button at the top right and click Create API Specification. Name your application SendSMSAPI or whatever you wish, choose Text Editor, RAML 1.0, and Save location: Design Center. Then click Create Specification.

When you first open up API Designer, you will be placed into the root file which contains your RAML code. We are going to first create a Library and DataType before we start building out our root file. The library will allow us to abstract our RAML code out of our root file. After we add our library, we are going to assign our endpoint with a DataType which sets rules on how we are allowed to interact with our API. Create a new file by clicking the + and call it library.raml and make sure to set the Library DataType in the dropdown menu. Copy and paste the below code into your library.raml file:

#%RAML 1.0 DataType
properties:
 ToPhoneNumber:
   description: Enter the mobile number to send a text
   example: 15553334444
   type: integer
   required: true
 Message:
   description: Enter your message
   example: Text message body
   type: string
   required: true

As you can see, we set each of the fields to be required, or else the API will return a 400 response. We also defined that each value must be an integer for the phone number and string for the message. You can see the changes reflected on the preview window on the right-hand side of API designer.

Finally, we have to add our Library and DataType to our root raml file. Add the following code to your root raml file:

mediaType: application/json
uses:
 library: library.raml
/text:
 type: library.text

As you can see, we are importing our library.raml file in our root file, and are referencing the text variable under type: library.text. We are defining that /text will be our endpoint, and that the endpoint should follow the rules set in the library under library.text.

When you save your root file, and enable the mocking service on the top right, you will see a preview of your API on the right-hand side of the screen. You can see with DataTypes and Libraries, that we were able to abstract all of the code out of the main raml file. Additionally, the mocking service window still generates all of the previews needed to properly interface with the API.

Next, create a new file, and call it securityScheme.raml and make sure to select the Security Scheme option from the drop-down menu. Copy and paste the following code into your securityScheme.raml file:

#%RAML 1.0 SecurityScheme
type: Basic Authentication
describedBy:
 headers:
   client_id:
     type: string
   client_secret:
     type: string
 responses:
   401:
     description: Unauthorized or invalid client application credentials
   500:
     description: Bad response from authorization server, or WSDL SOAP Fault error

Once we deploy our API later in this tutorial, you will find the same RAML code located above under the API Specification snippet in API Manager. This code will generate when you apply a new policy to your already deployed API.

Next, go into your library.raml file and paste the following code under usage:

securitySchemes:
 clientIDrequired: !include securityScheme.raml

Now navigate back to your root raml file, and added the following code under the title variable:

securedBy:
 - library.clientIDrequired

This code will now secure the entire API with Basic Authentication security, which means users will have to provide a client_id and client_secret that’s issued to them by API manager

Now it's time to try out the API. Enable the mocking service, and click the send button to send a test payload. If you get the desired 200 OK response, you’ve done it! Now click the Publish button, and publish your API Specification to Exchange.

Open up Anypoint Studio and go to File -> New Mule Project. Enter your project name, and click the green plus button to import your API from Exchange. Search for your API in the search bar, then click the Add > button.

When you add the API Specification to your, Anypoint Studio will automatically apply scaffolding to your project using API Kit. Scroll down to the post:\text:application\json flow, we are going to build out our Twilio integration in this flow. The first step is to add an HTTP listener connector to the flow. Set the Path to: /text and when setting up the HTTP Listener config use:

Protocol: HTTPS
Host: 0.0.0.0
Port 8082

To set up HTTPS, you will need to generate a keystore on your local machine. It’s super easy to do, and is just one line in the terminal. For instructions, please click here to see how to generate a keytool keystore.

Once you have generated your keystore, in the TLS section of the HTTP Listener, under Key Store Configuration, set:

Type: JKS
Path: yourkeystore.jks
KeyPassword: YourPassword
Password: Password

Click Test Connection to verify that it worked correctly.

Next, drag the HTTP Request Connector into your flow and set the HTTP Request config to:
Protocol: HTTP
Host: 0.0.0.0
Port: 8081

Click Save. Go to the Request section, and for Method type: POST and for the URL type:

http://api.twilio.com/2010-04-01/Accounts/YOUR-ACCOUNT-SID-GOES-HERE/Messages.json

Don't forget to put in your account SID from Twilio in the URL. Then go to the Request body and add the following code:

output application/x-www-form-urlencoded
---
{
    "To":payload.ToPhoneNumber,
    "From": 14085835493,
    "Body":payload.Message
}

Next, under headers enter the code below. Make sure to press the fx button to allow you to enter your DataWeave code. Keep in mind where it says Account SID and Auth Token, you will get those both from your Twilio Dashboard. We combine both of the token values into the basic authorization format by using base64 encoding.

import toBase64 from dw::core::Binaries
output application/java
var concat = "ACCOUNT-SID" ++ ":" ++ "AUTH TOKEN"
var base64 = toBase64(concat)
---
{
    "Authorization" : "Basic " ++ base64
}

In order to deploy your application, you must first setup API Autodiscovery so we can assign security policies to our API. Log into Anypoint Platform and go to API Manager. In API Manager, click on the Manage API button, and click Manage API from Exchange. Find the API you created, and make sure to check the box saying you are using Mule 4 and above. Click Save, then click on the API and copy and paste the Autodiscovery API ID.

Go back into Anypoint Studio, and click on the Global Elements tab. Click the Create button, and search for API Autodiscovery. Paste in your API ID into the window and select your main flow under flow name.

Now right-click on your project folder, and click Anypoint Platform, Deploy to Cloudhub.

In order for API to autodiscover, we need to include our anypoint platform client ID and secret under Properties upon deployment. See the screenshot below.

To find your client id and secret, go to Anypoint Platform, navigate to Access Management, Environments, and click on whatever environment you are deploying on (whether that is Sandbox, Production etc), and copy and paste your client id and secret into the corresponding fields on the deployment screen. Finally, click the deploy button! Nice work.

Navigate to Anypoint Platform, and go to API Manager. Click on your now Active API and got to Policies, then click the Apply New Policy button. Select the Client ID enforcement policy, leave all the settings as default.

When you apply this API level policy, making any POST request to your API endpoint will result in an error if you don’t include the proper headers. To grab your client ID and client secret for your API, go to Exchange, search for your API, and click Request Access. Enter your API Instance, your Application, and then click Request Access. This will generate your unique client ID and client secret that you will use to send POST requests to your API.

As you can see from the screenshot below, you will get a 401 unauthorized response if you don’t include the proper client_id and client_secret headers in your request.

However, when you enter both of the headers correctly based off the keys you get from Exchange, your text message will successfully be sent through Twilio.

We hope that this tutorial was helpful and helped walk you through the main steps of designing, developing, and deploying an API. Now that you have a good idea on how to build your first RAML specification and successfully deploy, take a look at our developer tutorials homepage where you can find more tutorials related to API design and development. Please rate this article and your feedback below.

Five aspects of RESTful API design

Alex Theedom — Mon, 03 Aug 2020 12:21:34 +0000

There are five principal aspects to a RESTful API specification that must be considered prior to coding an API specification.

In this post I will discuss those five features with examples using a product use case.

If you are already familiar with API design and want to go deeper, I suggest that you take a look at the tutorial: How to design RESTful APIs with the API Designer.

Before I get started let's ensure that we understand what is meant by API and REST.

What is an API?

An Application Programming Interface (API) is a set of rules that define how a software component can interact with another software component.

In the context of a web service those interactions relate to the manipulation and retrieval of data in accordance with the four basic functions of persistent storage: create, read, update, and delete (CRUD).

The style in which these rules are defined is referred to as the “REST architectural style”. This was devised by Dr Roy Fielding in his 2000 PhD dissertation “Architectural Styles and the Design of Network-based Software Architectures”.

What is REST?

REST stands for REpresentational State Transfer. It provides a way to represent resources (i.e. data) and transfer it over HTTP by calling a URI. The URI represents the data as a noun and the data function (CRUD) is represented by an HTTP method. Typically the HTTP methods map to CRUD functionality as should in the following table.

CRUD functionality	HTTP method
GET	Read
POST	Create
PUT / PATCH	Update / Partial update
DELETE	Delete

RESTful API spec design

The API designer has a choice of RESTful modeling languages to use for the implementation of the API design. Here are two of the most widely used:

OAS (Swagger)
RAML (RESTful API Modeling Language)

Each has its own approach to specifying as API design and each with its pros and cons, nevertheless they both respect the REST architectural style.

I choose to use RAML in this blog post as I believe it's the most intuitive modeling language available for those that are not familiar with API modeling languages.

The REST API design tool that I will use in this article is the highly productive tool used in the tutorial How to design your first API with API Designer from MuleSoft. This tool is ideal for designing RESTful APIs with RAML or Swagger (OAS 2 and 3). However you can use whichever tool suits you.

The product use case

To add context to the specification I will define a use case. Let's imagine that our company has asked for an API that represents product data. The REST API will expose functionality that in accordance with full CRUD functionality and the API specification must documentation the product data type and provide examples.

Let’s get started by defining the header of the API specification.

Define the API header

I will start by defining the header of the specification file in which I define the API title (for display purposes), the asset version, and the base URI at which the implementation will be deployed.

#%RAML 1.0
title: Products API
baseUri: http://big-product-company.com/api/{version}
version: v1

Next, I will define the resource representation for our products.
Define the resource URIs

The resource URIs represent the product data and it is these URIs against which CRUD functionality can be performed, thus representing the actions for Create, Read, Update and Delete.

In order to respect the REST conventions, the resource URIs are named as nouns that relate to the actual data it represents. Common resources might be represented as shown in the table below:
Resource URL

Resource URL	Data type
/accounts	Account data
/invoices	Invoice data
/users	User data

The expectation of the REST style is that a call to the GET /products endpoint will return a list of products (even if the response contains only one product) and therefore, as the resource represents a collection, the nous is pluralized. The RAML syntax states that the resource URI must be terminated with a colon :

/products:

Once the resource URI is defined, the CRUD functionality that we want to operate on those resources, is specified using HTTP methods.

Define HTTP methods for resource URIs

As shown above, there are five HTTP methods defined for use by developers of REST API specifications.

The REST style states that the GET and POST HTTP methods are used with a single URI resource as they don’t target an identifiable resource but rather a list of resources. Conversely, the DELETE, PUT and PATCH HTTP methods are accompanied with a URI variable that identifies the resource being affected. Take a look at the code below.

/products:
 get:
 post:
 /{productID}:
   put:
   delete:

Notice how the GET and POST methods are used with the /products URI and the PUT and DELETE are used with the /products/{productID} URI.

The POST and PUT endpoints must include a resource presentation, in our case a product to create (POST) or update (PUT). The request body must be defined in the specification so it is clear to the caller what data must be sent and in what format.

Define the HTTP requests

To satisfy the REST requirement for clear resource representation the API spec must define a data type and provide a valid example of the data. In our case this will be a data type that defines the structure of the product and an example.

It is also a requirement (actually its a strong recommendation) to specify the data interchange format. Typically this is defined as a MIME type, such as JSON and XML, and can be one of many types.

For our use case lets add an example to each endpoint and define a MIME type.

In the RAML below the product GET, POST and PUT endpoints are defined with an example of the product data for the POST and PUT. The data interchange format is defined as application/JSON.

/products:
 get:
 post:
   body:
     application/json:
       example: |
         {
           "name" : "Bed",
           "price" : "100"
         }
 /{productsID}:
   put:
     body:
       application/json:
         example: |
           {
             "name" : "bed",
             "price" : "100"
           }
   delete:

For each request made to the API and response is expected and should be defined in the RESTful API specification. Let’s take a look at how this is done.

Define the HTTP responses

In response to a request the caller expects to receive a body containing data (or at least a message) and an HTTP status code indicating the status of the requests. HTTP status codes fall into one of five categories as show here:

1xx -> Informational
2xx -> Success
3xx -> Redirection
4xx -> Client Error
5xx -> Server Error

The first digit of the status code identifies the status of response. A full list of status codes can be found here.

For our product example let’s define a response for the GET and DELETE methods. I am going to define a 200 code for the GET and DELETE request to indicate a successful operation.

/products:
 get:
   description: Retrieve the list of all products
   responses:
     200:
       body:
         application/json:
           example: |
             {
               "name" : "Bed",
               "price" : "100"
             }
 post:
 /{productID}:
   put:
   delete:
     responses:
       200:
         description: Delete the product with id {productID}

Now we have defined all the main aspects of an API specification let’s put it all together.

Putting it all together

The complete RESTful API design looks as follows:

#%RAML 1.0
title: Products API
baseUri: http://big-product-company.com/api/{version}
version: v1

/products:
 get:
   description: Retrieve the list of all products
   responses:
     200:
       body:
         application/json:
           example: |
             {
               "name" : "Bed",
               "price" : "100"
             }
 post:
   body:
     application/json:
       example: |
         {
          "name" : "Bed",
          "price" : "100"
         }
 /{productID}:
   put:
     body:
       application/json:
         example: |
           {
             "name" : "Bed",
             "price" : "100"
           }
   delete:
     responses:
       204:
         description: Delete the product with id {productID}

Final thoughts

In this tutorial I have shown five aspects of API specification design using RAML as the RESTful API modeling language. I have covered how to define resources, methods, requests and responses in accordance with the REST architectural style.

If you want to dive deeper into API design I recommend you take a look at the How to design your first API with API Designer tutorial.

Mule Invaders: Use APIs to get a high score

Jordan Schuetz — Tue, 07 Jul 2020 17:07:57 +0000

Welcome developer

Welcome to Mule Invaders, the video game inspired by the classic retro shooters Galaga and Space Invaders. In Mule Invaders, help Max the Mule destroy waves of enemies by spawning powerups using APIs. To protect Max on his journey to integrate the universe, create APIs in Anypoint Platform, deploy your application on CloudHub, then make HTTP requests to your APIs to spawn powerups while playing the game in realtime. When you use a REST client to send a POST request to your API, the flow will run and will trigger a powerup to spawn in the video game. The more powerups you trigger, the higher the score you can get.

So, what are you waiting for? Download Mule Invaders today by using the below links for Windows or Mac, and then build your integration by following the steps below.

Step 1: Signup for Anypoint Platform

To play Mule Invaders and build your first API or integration with MuleSoft, go to the tutorial to signup for a free account

Step 2: Build the integration

Now that we have created our MuleSoft account, let's developed the backend logic of the video game using Flow Designer. If you click the blue button below, you will be taken to the Mule Invaders Exchange page where you can download and modify the integration right in your web browser. When you navigate to Exchange by clicking the button below, click Open Flow to open up the integration in Design Center.

Download Mule Invaders on Exchanage

Once you click Open Flow, you will need to click: Use this template which will import the entire project into your Anypoint Platform account. When you are prompted to provide a name for the Mule Applicaiton, name it: MuleInvaders.

When you click on the Use this template button, you will see some errors when loading the project. These errors are can be fixed easily! All you have to do is set up your HTTP Listener. An HTTP Listener is a very helpful Connector that enables you to listen to a URL for any new HTTP Request. When a new HTTP request is received by the HTTP Listener, anything that comes after the HTTP Listener in the flow will be executed at runtime.

To set up the HTTP Listener, click on cloudhub_http on the left navigation bar, and then click Add Connection. Insert the credentials listed in the screenshot below by adding the Host as 0.0.0.0 and the Port as 8081.

Once you have added the HTTP listener credentials, click Save and you will notice that all the errors in the project will disappear.

How does the Mule Application work?

In the video game Mule Invaders, there are four powerups that you can unlock in the actual game through sending an HTTP request to one of the API endpoints we have just created. The main endpoint, /hack is the main endpoint that the game client is listening too. The game detects when a new UUID has been added to the Object Store under that endpoints unique key. When a new UUID has been added, the powerup will spawn in the video game. This works since the game polls the /hack endpoint for any new update to the object store twice a second.

Here is a brief description of what each endpoint will do in the video game Mule Invaders:

/hack

This is the endpoint that the Mule Invaders client application listens to and polls to listen for a new update from the KV Store.

/spawnshield

SpawnShield gives the player invincibility for 5 seconds and protects the player from incoming vulnerabilities. You can see in-game that the text will flash “protected by Anypoint Security” when the shield is spawned.

/powerlaser

PowerLaser gives the player a spread laser cannon that changes the particle to red and allows you to kill enemies faster.

/api-blaster

API Blaster increases the fire rate of laser cannons. Pew pew pew.

/spawnscore

Spawn score gives you bonus +1000 points and creates the slot machine sound effect.

Ready to play?

Now that you understand how the Mule application was built, and how each API endpoint affects the video game, go up to the top right of the Flow Designer window and click the Test button to try out the integration you just built.

To test the integration, insert the mocking service URL into a REST client such as Postman, and make a POST request to the endpoint URL that you just created (don't forget to add /hack on the end of the URL). Once you make the HTTP request, you should see is a null value response for each JSON key in all request body. This is because we currently have no values added in the Object Store under those key names.

To add a new value to the Object Store, change your request URL to /spawnscore instead of /hack and send an additional POST request.

Now once again change your request URL back from /spawnscore to /hack again, and you will notice that score now has a UUID assigned under that JSON key.

This JSON payload is how the game is able to detect if a new request has been made. Pretty simple right?

Publishing your integration

Now that you understand how the Mule Application works, let's publish our application to CloudHub so we can get a dedicated URL for our application to run on. Click the drop-down arrow at the top right-hand side of the project and click the Deploy Application button. Select your target environment as Sandbox and name your application whatever you wish (must be a unique name). It will take a few minutes for your application to deploy, however when it finishes, navigate to Runtime Manager, then switch your environment to the one you selected which is Sandbox. The application should be illuminating a green dot stating that it is running. Click on the application, and grab the URL from the top of the page, copy it into your URL bar, and add http:// to the beginning and add the /hack endpoint to the end of the URL. That URL including the /hack endpoint will be the URL you insert into the video game.

Step 3: Download Mule Invaders

Next, we are going to download the Mule Invaders application for either Mac or PC. Each build will come in a compressed zip folder that you will have to unzip on your local machine.

Mac Download
Windows Download

For Mac, when you open the application, you will get a warning saying that this application is not verified. To run the application, navigate to your Mac's System Preferences, then click on Security and Privacy, then click on Open Anyway. On PC, simply just click Run Application.

Congratulations developer

Congratulations on completing all the steps to this tutorial. Now it's time for the fun part, let's play the game. When you launch the application, you will be greeted by the below screen which will prompt you to enter your CloudHub URL. Copy and paste the URL including the http:// and the /hack endpoint. Control your character using the WASD keys and fire your blaster with the space bar. Exit the application at any time by pressing the ESC key.

To spawn powerups in Mule Invaders with the APIs you just created, open up Postman and send HTTP POST requests to either /spawnshield, /powerlaser, /api-blaster, /spawnscore. As an extra challenge, see if you can create a front end or mobile application that sends API requests to the endpoints for you. You can see an example front end application located here.

If you have any issues with the application not spawning the powerups, make sure to check that your CloudHub URL is correctly entered.

Thanks again for trying out Mule Invaders. Want to keep learning how to develop powerful integrations and APIs with the MuleSoft platform? Visit our developer tutorial catalog for tutorials for all experience levels.

Enjoy the game? Tweet us your high score on Twitter @MuleDev