Insites Docs Developers guide APIPersisting Part of a Third-Party API Response

Persisting Part of a Third-Party API Response

Last updated on June 26, 2024.

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

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

Note

This step can be performed using the Instance Admin. Please refer to the Profiles documentation for more details.

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.

Note

Steps 5-7 can be done using the Instance Admin. Please visit the following documentation for more details:


Have a suggestion for this page?

Didn't quite find what you are looking for or have feedback on how we can make the content better then we would love to hear from you. Please provide us feedback and we will get back to you shortly.