Persisting Part of a Third-Party API Response

This document shows you how to persist an API response from a third-party system.

Prerequisites

To follow the steps in this tutorial, you must understand basic Insites concepts and topics such as Pages, Users, and Notifications

• Development Workflow
• Pages
• Users
• Notifications

Steps

Persisting part of a third-party API response is a seven-step process:

• Step 1: Creating a Profile and a Database Field for the API Response
• Step 2: Creating a test endpoint
• Step 3: Creating an API call notification
• Step 4: Creating a GraphQL mutation
• Step 5: Creating a page to embed a form on
• Step 6: Creating and embedding the form on the page
• Step 7: Displaying the results

Step 1: Creating a Profile and a Database Field for the API Response

Create a new user profile called , and create a database field with which to store the value from the API called :

app/user_profile_types/default.yml

Step 2: Creating a test endpoint

Create a test endpoint that simulates a third-party API JSON response:

app/views/pages/test-endpoint.json.liquid

Step 3: Creating an API call notification

Create an API Call Notification that should:

1. send a request to
2. store the value from the response in a property

Replace with your domain:

app/api_calls/send_request.liquid

Step 4: Creating a GraphQL mutation

The tag invokes a GraphQL mutation in the callback with the provided arguments. The query accepts two arguments: the , the user ID we want to update, and the , which is the value we want to store. The content of the GraphQL mutation file:

app/graphql/persist_in_custom_attribute.graphql

The mutation passes the arguments to a form called . Make sure that its configuration includes the fields you want to persist. Please note: by re-using an idea of here, you can easily send additional emails, SMSes, or even other API calls. All you want to do in this example is store the value, so you don't have to add any additional notifications.

app/forms/callback_persist_in_custom_attribute.liquid

Step 5: Creating a page to embed a form on

Once an API Call Notification is defined, you should associate it with a form to trigger it. Create the following page to embed this form:

app/views/pages/test-form.liquid

Step 6: Creating and embedding the form on the page

Create the form and associate it with the API Call Notification. It can be a sign-up form that creates the in the background:

app/forms/test-form.liquid

Once the user fills out the signup form without validation errors, the system will trigger the API Call Notification. The callback will run the GraphQL mutation, using to persist the data. If it is successful, it will trigger the callback, in which you will have access to the server's response via the variable. You can access various things like  and, most importantly, .

Step 7: Displaying the results

In the , you have set up a redirection to , so create this page and make it display the :

app/views/pages/test-result.liquid

It uses the following GraphQL query:

app/graphql/get_current_user_third_party_api_value.graphql

You can now go to the /test-form page, provide sign-up details, and click the Save button. Initially, the correct value will not be there because the API call is triggered in the background, outside of the request lifecycle. However, when you refresh after a couple of seconds, the value has been populated. This behaviour is essential so that the system relies on something other than a third-party API's availability.