The Fundamentals of Connecting Logic to External APIs

Logic's Make HTTP Request block opens up a world of capabilities. At any point in your flow, you can connect your Logic flow to external services to send, receive, and transform your data.

Before you begin, read this doc. Knowing these things will make your integrations far more smooth.

Configuring Authentication

API keys

Many services use API keys as the preferred form of authentication.

• These are usually accessed inside of that system's account, but can be found in different places. Look for "Integrations" or "Developers", or check under your Account settings to locate these.
• You may end up creating several API keys, so if the service has the ability to assign an name, use a recognizable one, like "mysite.com / Logic".
• In many services, once you've generated your API key you are no longer able to view it again, ever. Plan to store these securely somewhere like a password keeper, in case you need it again.

Authenticating your HTTP Request Blocks in Logic

Before you begin an integration, locate the API documentation for that service. Typically at the top you'll see a section called Authentication or Meta.

This section contains the important details needed to connect to the API.

Details will vary, but here are some key things to look for.

Perhaps the most common API authentication scheme I see is API token authentication, with the API key passed in the Header.

In that situation, these are typical settings;

• Authentication - select API token
• Add to - select Header
• Header - depends on the API. It's generally something like _Api-Token, or _{Authorization}. Check the docs.

Logic Credentials

In Logic, the API key will be stored in a Credential, which you create in Logic.

It's very important to look for a prefix string here, like _Token or _Bearer. In the docs, you may see this described as;

_{Api-Token: Bearer YOUR-TOKEN-HERE}

In your Logic Credential, you MUST include that prefix string inside of your token value, if one is specified. This means that you'd copy your API key, but when you paste it into your Logic credential, you'll first need to type, e.g. _Bearer  first. Make sure to have a single space between this prefix string, and your API token value.

Base URL

To create the URL for your call, you'll need to make sure you know the Base URL to use. For some services this will be a static string like;

_{https://api.service.com/api/v1}

And you'd add your command to that, e.g. _/subscriber

In other services that Base URL will be specifically given to you for your geographic part of the world, or even for your specific account.

Make sure to check the API docs to determine what you should use.

Configuring Body Content

In RESTful APIs, when you're creating or updating content, you will typically use POST or PATCH with request body content.

In most modern APIs, that body is typically JSON.

Request Headers

Often, you'll need to announce to the receiving API what format you are sending the content in. If this is JSON content, you'll need to add this header to the Headers section.

_Content-Type : _{application/json}

Editing JSON

JSON stands for JavaScript Object Notation, and it describes a simple data format that looks something like this;

_{{
  "email": "web@sygnal.com",
  "fields": {
    "name": "Mike"
  },
  "groups": [
     "2374982734982437",
      "8257981983798122"
   ]
}}

Key things to note;

• There will always be an outer pair of braces _{{ }}
• Inside, you'll se key-value pairs, represented as e.g. _{"key": "value"}
• The value portion can be another object, which will also be wrapped in braces _{{ }}
• The value can also be an array, which is wrapped in brackets _{[ ]}
• In arrays, you can have a list of values, or you can have a list of objects
• Every key, and every value, must be wrapped in double-quotes
• Commas are essential, to separate siblings in any part of the JSON structure

If you have certain special characters inside of your values, you must escape them as follows;

• Backspace to be replaced with _\b
• Form feed to be replaced with _\f
• Newline to be replaced with _\n
• Carriage return to be replaced with _\r
• Tab to be replaced with _\t
• Double quote to be replaced with _\"
• Backslash to be replaced with _\\

Common mistakes;

• Missing characters such as quotes, commas
• Having extra spaces inside of the double-quotes in a key or value item
• Missing a closing brace or bracket
• Confusing objects v. arrays

Adding your JSON to Create and Update requests

JSON will go into the Body field at the bottom of the configuration for the Make HTTP Request block.

NOTE: It appears as a single line, which may be confusing, however it will expand to fit your content.

Usually the easiest way is to simply copy and paste example JSON from the API docs you are reading, and then modify it as desired.

Adding Fields

To insert data into the JSON, use the purple + Insert Field icon in the corner of the Body field.

Fallback Values

Logic uses fallback values to guarantee that every field you use has a value.

When you place fields in your JSON Some fields may require fallbacks. In simple terms, that means you need to specify a secondary "fallback" value that it can use when necessary.

If you see a yellow wrench icon, this is what's being indicated. To add those, click the gear at the right end of the field.

If you do not have any valid fallback value, which does happen, Logic will accept a single space as a valid fallback.

Publishing Your Logic Flow

You cannot publish your logic flow until you complete three things;

• Publish your website ( staging is fine )
• Complete all of the configuration tasks, so that there are no more yellow wrench icons.
• Test your flow, at least once.

Once this is done, you can click the Update Flow button in the top right corner, and you will be given the option to turn the flow on.

‍