External APIs
Overview
External APIs enable Creators to build versatile Centauri (v1.0) and Vega (v2.0) applications connecting to thousands of other services. 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.
About External APIs
Unqork lets Creators integrate external API services into environments. 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, set up the external service in Services Administration. Then, configure the API with a Plug-In component to make the call.
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 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 are not the only settings on the page, but they’re the minimum required for an external API call. In rare cases, Creators 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.
Learn how to create and add a service in our How To: Add a Service article.
How to Make an External API Call
For this example, set up a SendGrid API call to send emails automatically. In Unqork, you can trigger an API call to SendGrid based on end-user interaction. When an end-user clicks a button, it triggers an API call to SendGrid. Then, SendGrid sends the email.
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.
Preconfiguration
Configure the External Service
First, configure the SendGrid service in Services Administration. To get the necessary information, use SendGrid's API documentation: https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/index.html.
1. | At the top right of the Unqork Designer Platform, click Administration. |
2. | Under Integration, click Services Administration. |
3. | Click + Add a Service. The Create New Service modal displays. |
4. | In the Service Title* and Service Name* fields, enter SendGrid. |
5. | Click Next. |
6. | In the Share To field, specify if the service is shared with the Environment, or a specific Workspace. |
7. | Click Create. The service page loads for the new service. The service can now be configured. |
8. | In the top right of the page, click Edit. |
9. | From the left menu, click the Service Type button. |
10. | In the Service Protocol + Host* field, enter https://api.sendgrid.com/v3. |
11. | From the Authentication Method* drop-down, select Bearer Token. |
12. | In the Bearer Token field, enter your Bearer Token value. |
This Bearer Token is unique to every SendGrid user. The Unqork Training environment uses Unqork's SendGrid Bearer Token.
13. | Click Save Changes. |
Configuration
Configure a module to use the Sendgrid API service. Set up an Email and Text Area component to contain an end-user's message, then send that data using the Sendgrid API.
Configure the Columns Component
This Columns component acts as container to keep a module organized. You'll use the component to contain an Email and Text Area component.
1. | In the Module Builder, drag and drop a ![]() |
2. | In the Property ID field, enter colEmail. |
3. | Click Save Component. |
Configure the Email Component
This Email component serves as the recipient of the email. In a later step, you'll map this to the SendGrid API call using a Plug-In component.
1. | Drag and drop an ![]() ![]() |
2. | In the Property ID field, enter emailAddress. |
3. | In the Label Text field, enter Email Address. |
4. | Click Save Component. |
Configure the Text Area Component
This Text Area component serves as the body of the email. In the next step, map this to your API call using the Plug-In component.
1. | Drag and drop a ![]() ![]() |
2. | In the Property ID field, enter emailMessage. |
3. | In the Label Text field, enter Email Message. |
4. | Click Save Component. |
Configure the Plug-In Component
Use a Plug-In component to map the data parameters into a single request body.
1. | Drag and drop a Plug-In component onto your canvas, placing it below the colEmail ![]() |
2. | In the Property ID field, enter pluginSendEmail |
3. | In the Canvas Label Text field, enter pluginSendEmail |
4. | From the Service Type drop-down, select External. |
5. | From the External Services drop-down, select the Sendgrid service set up in the Pre-Configuration steps. |
6. | In the Data Source URL field, enter mail/send. |
7. | From the Request Type drop-down, select Post. |
The Service Protocol + Hostvalue entered earlier pre-populates here. This is consistent for any call made using SendGrid. Adding mail/send specifies that you are sending an email in this specific call.
8. | In the Inputs table, enter the following: |
Property ID |
Mapping |
|
---|---|---|
1 |
emailAddress |
personalizations[0].to[0].email |
2 |
emailMessage |
content[0].value |
3 |
'training@unqork.com' |
from.email |
4 |
‘Hello Subject’ |
subject |
5 |
‘text/html’ |
content[0].type |
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.
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.
9. | Click Save Component. |
Configure the Button Component
Lastly, configure a Button component to trigger your Plug-In component. When you click this button in Express View, the Plug-In component makes the API call.
1. | Drag and drop a ![]() ![]() |
2. | In the Property ID field, enter btnSendEmail. |
3. | In the Label Text field, enter Send Email. |
4. | Navigate to the Actions settings. |
5. | From the Action Type drop-down, select Event. |
6. | In the On Click field, enter pluginSendEmail. |
7. | Click Save Component. |
8. | Save your module. |
Your completed module configuration looks like the following in the Module Builder:
Click Preview to test your configuration 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.