External APIs

Overview

To build a versatile application, you sometimes need to connect to an external API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. (application programming interface). For example, if you need to add a map feature to your application, you might use a Google Maps API. Doing so lets you avoid having to build the map yourself.

What You’ll Learn

In this unit, you'll learn about external APIs, how to set them up, and how to make an external API call.

About External APIs

Unqork lets you integrate external API services into your environment that Unqork’s API doesn't already offer. For example, connecting to a CRM (customer relationship management) system, or integrating with a Salesforce instance and DocuSign account.

Making an external API call requires a little extra work compared to an internal API call. First, you need to set up the external service in Services Administration. Then, to make the call, you need to configure the API with a Plug-In component.

Setting 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 four pieces of information:

Setting

Description

Service Title

This title displays in the External Services drop-down in the Plug-In component. Typically, 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 avoid 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 a specific API call.

Type of Authentication

This is the method of authentication the service or application uses. The service provider determines which method to use. If you're unsure of the authentication type, refer to the API service'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 using the API. Or, you might need to include certain items in each request body. For more details on each setting, visit the Services Administration article.

How to Make an External API Call

With your external API service set up, you can now make an external API call. For this example, you'll set up a SendGrid API call to send emails automatically. In Unqork, you can trigger an API call to SendGrid based on end-user End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. interaction. When an end-user clicks a button, it triggers an API call to SendGrid. Then, SendGrid sends the email.

What You Need

Before starting this configuration, you'll need the following:

TIP  When configuring API calls, it's best practice to use a Proxy module. Because this example focuses on configuring the API call, you won't create a Proxy module. To learn more about setting up Proxy modules, see our How to: Add a Proxy Module to a Remote Execute article.

Pre-Configuration

Configure the External Service

First, you must configure the SendGrid service in 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.

1. At the top right of the Unqork Designer Platform, click the Settings ▾.
2. Select Administration.
3. Under Integration, click Services Administration.
4. Click + Add a Service. The Create New Service modal displays.
5. In the Service Title* and Service Name* fields, enter SendGrid.
6. Click Create. The service page loads for the new service. The service can now be configured.
7. In the top right of the page, click Edit.
8. In the Service Protocol + Host* field, enter https://api.sendgrid.com/v3.
9. From the Authentication Method* drop-down, select Bearer Token.
10. In the Bearer Token field, enter your Bearer Token.

NOTE  This Bearer Token is unique to every SendGrid user. The Unqork Training environment uses Unqork's SendGrid Bearer Token.

A static image displaying the service configuration, including selecting the Bearer Token authentication type.

11. Click Save Changes.

Configuration

With your service configured, open your module to finish the configuration to make a SendGrid API call.

Configure the Columns Component

This Columns component acts as container to keep your module organized. You'll use the component to hold an Email and Text Area component.

1. In the Module Builder, drag and drop a Columns Component Icon Columns component onto your canvas.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module.  field, enter colEmail.
3. Click Save & Close.

Configure the Email Component

This Email component serves as the recipient of your email. In a later step, you'll map this to your API call using a Plug-In component.

1. Drag and drop an  Email component onto your canvas, placing it inside the left-hand column.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module.  field, enter emailAddress.
3. In the Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. field, enter Email Address.
4. Click Save & Close.

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 Icon Text Area component onto your canvas, placing it inside the right-hand column.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module.  field, enter emailMessage.
3. In the Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. field, enter Email Message.
4. Click Save & Close.

Configure the Plug-In Component

Use a Plug-In component to map your parameters into a single request body.

1. Drag and drop a Plug-In component onto your canvas, placing it below your Columns Component Icon Columns component.
2. In the Property ID and Canvas Label Text fields, enter pluginSendEmail.
3. Set 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. Set Post as the the Request Type.

NOTE  The Service Protocol + Host you entered earlier prepopulates here. That is consistent for any call made using SendGrid. Adding mail/send specifies that you are sending an email in this specific call.

7. In the Inputs table, enter the following:

Property ID

Mapping

emailAddress

personalizations[0].to[0].email

emailMessage

content[0].value

'training@unqork.com'

from.email

‘Hello Subject’

subject

‘text/html’

content[0].type

NOTE  Setting any of these inputs as Required stops the API call from sending if the value is not present. Setting an input as Optional means the call sends without the parameter rather than as a blank value if that parameter is empty.

NOTE  You can find the parameters for external API calls in the service's documentation. You need to include every required parameter for your call to succeed. You can find the SendGrid documentation here: https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/index.html.

A static image displaying the completed configuration of the Plug-In component in the Module Builder.

8. Click Save.

Configure the Button Component

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

1. Drag and drop a Button component onto your canvas, placing it between the Columns Component Icon Columns and Plug-In components.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module.  field, enter btnSendEmail.
3. In the Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. field, enter Send Email.
4. To the left of the component's configuration window, click Actions Icon Actions.
5. Set Event as the Action Type.
6. In the On Click field, select or enter pluginSendEmail.

A static image displaying the completed configuration of the Button component with the Event Action Type and the on click triggering the Plug-In component.

7. Click Save & Close.
8. Save your module.

Your completed module configuration looks like the following in the Module Builder:

A static image displaying the completed component configuration in the Module Builder.

Click Preview to test your configuration in Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View.. Fill out the fields and click the Send Email button. If your call is successful, you'll receive an email at the email address you entered in Express View.

A static image displaying the completed configuration in Express View.

Resources