Persisting Part of a Third-Party API Response

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/test_profile.yml

name: test_profile
properties:
- name: third_party_api_value
  type: string

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

{
  "third_party_api_id": "id-1"
}

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

---
name: send_request
to: http://example.com/test-endpoint.json
format: http
request_type: GET
callback: "{%- assign response_json = response.body | to_hash -%}{% graphql res = "persist_in_custom_attribute", user_id: form.id, third_party_api_id: response_json.third_party_api_id %}"
request_headers: "{
  "Content-Type": "application/json"
}"
---
{
  "id": "{{ form.id }}"
}

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

mutation persist_in_custom_attribute($user_id: ID!, $third_party_api_id: String!) {
  user_update(
    id: $user_id,
    user: {
      profiles: [
        {
          name: "test_profile"
          values: { properties: [{ name: "third_party_api_value", value: $third_party_api_id }] }
        }
      ]
    }
    form_name: "callback_persist_in_custom_attribute"
  ) {
    id
  }
}

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

---
name: callback_persist_in_custom_attribute
async_callback_actions:
resource: User
fields:
  profiles:
    test_profile:
      properties:
        third_party_api_value:
---

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

{% include_form "test_form", id: context.current_user.id %}

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

---
name: test_form
resource: User
fields:
  email:
  password:
  profiles:
    test_profile:
      enabled:
redirect_to: /test-result
api_call_notifications:
  - send_request
---

{% form url: "/api/users/{{ current_user.id }}" %}
  <label for="email">Email</label>
  <input name="{{ form.fields.email.name }}" value="{{ form.fields.email.value}}" id="email" type="email">

  <label for="password">Password</label>
  <input name="{{ form.fields.password.name }}" id="password" type="password">
  {% if form.errors.password %}
    <p>{{ form.errors.password }}</p>
  {% endif %}

  <input name="{{ form.fields.profiles.test_profile.enabled.name }}" value="1" type="hidden">

  <button>Save</button>
{% endform %}

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

{% graphql graph_current_user = "get_current_user_third_party_api_value"  %}
Third Party Api Value: for {{ graph_current_user.current_user.email }}: {{ graph_current_user.current_user.test_profile.first.third_party_api_value }}

It uses the following GraphQL query:

app/graphql/get_current_user_third_party_api_value.graphql

query get_current_user_third_party_api_value {
  current_user {
    email
    test_profile: profiles(profile_type: "test_profile") {
        third_party_api_value: property(name: "third_party_api_value")
    }
  }
}

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 behavior is essential so that the system relies on something other than a third-party API's availability.