External APIs

Estimated Reading Time:  9 minutes

Overview

To build a versatile application, you sometimes need to connect to an external API (application programming interface). Think of this as partnering with an outside provider to gain extra functionality. For example, if you need to add a map feature to your application, you might use a Google Maps API. This is easier than building the map yourself.

What You’ll Learn

In this article, you’ll learn:

• About external APIs.

• How to set up an external service.

• How to make an external API call.

About External APIs

An external API is any API you integrate into your environment that Unqork’s API doesn't already offer. With external APIs, you can take advantage of features otherwise not found in Unqork. For example, you might need to connect to your client's CRM (customer relationship management) system. Or you might want to integrate with their Salesforce instance and DocuSign account. To build that functionality into your application, you use an external API.

Making an external API call requires a little extra work compared to an internal API call. First, you'll set up the external service in your Unqork environment. You'll use the Services Administration menu to do this. Then, you'll configure the API call using a Plug-In component.

How to Set Up an External Service

To make an external API call, the first step is to set up the service in your Unqork environment. To set up that integration, you need 4 main pieces of information:

Setting	Description
Service Title	This is how the service shows in the Services drop-down of the Plug-In component. Most often, you use the name of the application or service.
Service Name	The Service Name is permanent. As a best practice, keep Service Names simple and without spaces. For example, you might use googlemaps when setting up a Google Maps integration.
Service Protocol + Host	This refers to the URI (uniform resource identifier) for all API calls made with this service. The URI serves as a locator, telling the API where to direct the call. If any part of the URI is consistent for every call, enter that part here. You can always add to the URI when configuring your specific API call.
Type of Authentication	This is the method of authentication the service or application uses. The service provider determines which method they use. If you're unsure of the authentication type, refer to the API's documentation.

These aren't the only settings on the page, but they’re the minimum you need for an external API call. In rare cases, you might need to specify certain Request Headers for all calls made with this API. Or you might need to include certain items in each request body. For more details on each setting, visit the Services Administration article.

Once set up in Services Administration, you'll use a Plug-In component to make the API call. From here, the process looks a lot like making an internal API call.

How to Make an External API Call

When using Unqork, there's a good chance you'll use an external service called SendGrid. SendGrid supports the use of API calls to send emails automatically. In Unqork, you can trigger an API call to SendGrid based on user interaction. For example, you can set a Button component that, when clicked, triggers an API call to SendGrid. This results in SendGrid sending an email.

This is what your completed module looks like in Express View:

And this is what your completed module looks like in the Module Editor:

What You’ll Need

To set up this use case, you’ll need:

• 1 Columns component.

• 1 Email component.

• 1 Text Area component.

• 1 Plug-In component.

• 1 Button component.

NOTE  When configuring API calls, you always need to use a Proxy Module. But, because this use case focuses only on configuring the API call, you won't create a Proxy Module here. You'll configure the API call in the main module.

Pre-Configuration

Configure the External Service

SendGrid is an external service, so you first need to add it under Services Administration. To get the necessary information, use SendGrid's API documentation found here: https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/index.html. This is where you find the authentication method and information for the API call.

NOTE  If you're completing this lab in a Training environment, SendGrid is likely already set up. Double-check the list of Active Services before completing this step. If SendGrid is on the list of Active Services, you can skip ahead.

1.

At the top right of the page, click the Settings tab.

2.

Select Administration.

3.

Under Integration, click Services Administration.

4.

In the Service Title and Service Name fields, enter SendGrid.

5.

In the Service Protocol + Host field, enter https://api.sendgrid.com/v3.

6.

From the Type of Authentication drop-down, select Bearer Token.

7.

In the Bearer Token field, enter your Bearer Token.

8.

Click Add Service.

Configure the Columns Component

Your columns act as containers to keep your module organized. Here, you’ll place your Email component and your Text Area component. These instructions assume that you have an open module saved with a title.

1.

Drag and drop a Columns component onto your canvas.

2.

In the Property ID field, enter colEmail.

3.

Click Save.

Configure the Email Component

This Email component serves as the recipient of your email. In a later step, you map this into your API call in the Plug-In component.

1.

Drag and drop an Email component onto your canvas. Place the Email component inside the left-hand column.

2.

In the Property ID field, enter emailAddress.

3.

In the Label Text field, enter Email Address.

4.

Click Save.

Configure the Text Area Component

This Text Area component serves as the body of your email. In the next step, you'll map this to your API call using the Plug-In component.

1.

Drag and drop a Text Area component onto your canvas. Place the Text Area component inside the right-hand column.

2.

In the Property ID field, enter emailMessage.

3.

In the Label Text field, enter Email Message.

4.

Click Save.

Configuration

Configure the Plug-In Component

As with internal API calls, the Plug-In component ties everything together. This is where you map out your parameters so they're all compiled into a single request body. For example, you take the data in your Email Address field and tell SendGrid that's the recipient. The Email Message field does the same thing for your content.

1.

Drag and drop a Plug-In component onto your canvas. Place the Plug-In component below your columns.

2.

In the Property ID and Canvas Label Text fields, enter pluginSendEmail.

3.

Select External as the Service Type.

4.

From the External Services drop-down, select SendGrid.

5.

In the Data Source URL field, enter mail/send.

6.

Select Post as the the Request Type.

7.

In the Inputs table, enter the following:

8.

Click Save.

Configure the Button Component

Finally, configure a Button component as the trigger for your Plug-In. When you click this button, the Plug-In sends the API call.

1.

Drag and drop a Button component onto your canvas. Place the Button component above the Plug-In.

2.

In the Property ID field, enter btnSendEmail.

3.

In the Label Text field, enter Send Email.

4.

Select Event as the Acton Type.

5.

In the Trigger on Click field, enter pluginSendEmail.

6.

Click Save.

7.

Save your module.

Now, test your configuration. In Express View, fill out your fields and click the Send Email button. If your call is successful, you'll receive an email at the address you entered in Express View.

Lab

You can view the completed lab for this use case here: https://training.unqork.io/#/form/5ee01120a6d2e20216dadaad/edit.