An Introduction to APIs in Celigo

Celigo is one of the most reputable iPaaS platforms in the market, especially when it comes to e-commerce process integration and automation. It’s a natural fit for businesses looking to automate their order-to-cash process between their e-commerce websites, ERP, and 3PLs. In general, It’s pretty much oriented towards data integration in order to sync data between all involved systems in any business process. However, this doesn’t mean that it doesn’t provide any API capabilities. In this article, we provide an introduction to APIs in Celigo by delving into its API capabilities and explaining the strengths and weaknesses of creating and leveraging APIs in this iPaaS platform.

Celigo Flows, Exports, and Imports

Before we start, It’s important to briefly explain Celigo’s integration model that revolves around three main components, i.e Flows, Exports, and Imports. Flows are nothing but the integration processes. They are the data-flows responsible to “export” data from source systems, “import” data into destination systems, as well as anything in between, such as transforming, filtering, or performing any kind of custom logic on the data. Exports are the components or connectors which exports the data from the sources, Imports are the components or connectors which imports the data into destinations.

Invoking APIs

In order to “Import” data into destination systems, Celigo provides a plethora of application-specific connectors, such as connectors for NetSuite, Shopify, Azure Blob, and many more. Celigo also provides universal connectors such as HTTP, Restful API, FTP, and GraphQL connectors. 

Using the HTTP or Restful API connectors, we can invoke any third-party API. Those connectors provide very powerful capabilities that could be very useful while invoking any external API. We’ll discuss some of these features next

Preview & Send

You can preview the API call and send an actual request directly when building the import

Non-Standard API Response Patterns

If the API you are trying to invoke does not behave in a standard way, you can easily override it’s behavior. For example, if the API always returns an 200 Ok response, regardless if there’s an exception or not, this section allows you to define where can you check in the response to determine if it’s a success or fail message

Exposing your Integration as an API

The other side of the coin is when you have a flow (or import / export), and you want to expose it as an API so that it can be invoked by external systems. This means that the trigger will no longer be controlled by Celigo integrator.io (manual or scheduled), it will rather be controlled by the caller. You have two options here, webhooks and My APIs

Webhooks

This is done by setting the import side of the flow to be a webhook listener. This means that rather than the integrator.io running and “importing” the data from the source, it will rely on the source to push the data to it. This is a perfect webhook scenario which allows you to expose your flow as an http-endpoint that could be invoked whenever an event occurs in the source system, for example when a customer is created in Salesforce, Salesforce can invoke your endpoint which triggers the flow which pushes the customer record to NetSuite.

To create a flow that is triggered via a webhook, open your flow and click on the “Add Source” icon as follows:

Select webhook from the list of options, then click “Next”

Populate the name, authentication details, and click on the “+” sign to generate a public URL for your flow

Now you can copy the generated URL and Save & Close the configuration

All what is left now is to invoke the endpoint from any external application. I’ll use Postman for the sake of this article

Note two observations: the HTTP status response is 204 No Content and the body is empty. This is because Celigo invokes the flow asynchronously. What is happening here is that by invoking the endpoint, you are effectively only triggering the execution of the flow and returning the response immediately to the caller, before the flow completes its execution.

My APIs

My APIs is Celigo’s way to create an API. It provides more flexibility than webhooks by allowing you to invoke an export, import, or a flow. It allows you to set your response HTTP status and body. Here’s a depiction of how this works taken from Celigo’s documentation

What you need to understand here is that invoking imports and exports is synchronous, so you could retrieve some data from a source system and return it back in the response, or insert some data into a destination system and return back a confirmation that data has been inserted. However, when invoking a flow, the invocation is still asynchronous and all what you are doing is triggering the execution of the flow. You can still customize the API response though.

In the next steps, we’ll show you how to create an API using My APIs in Celigo’s integrator.io

Step 1 – Enable the Developer mode

For the option to create APIs to be visible from the menu, you first have to go to your account settings and enable the developer mode, as per the image below. This is a one-time only operation.

Step 2 – Create an API & Script

First step to do when you want to create an API in Celigo is to navigate to My APIs menu item under “Resources” and click “Create My API” on the top right of the page.

You will be presented with your API page where you can populate some general information about the API such as the API name and description. Here, you have a shortcut to create a script or re-use an existing script. You need a script linked to the API since the script is the component that will invoke your import, export, or flow. Go on and hit the “+” icon under the Script section to create your script

Populate the script name and write your script inside the “content” text box as follows

Here’s the script you need to write. You could have returned the output of the flows.run as is, however I opted to filter the output and return the most useful fields only. Note that you would need to replace the flow id below by the id of the flow you want to run.

import { flows } from 'integrator-api' 

function _mainFlow (options) {
  let response = {};
  let invokeFlowResponse;
  let flowResponse;
  let output; 

  // Execute the Flow
  try {
    invokeFlowResponse = flows.run({_id:'64b3711fe837**************'});
    output = {
      "jobId": invokeFlowResponse._jobId,
      "exportId": invokeFlowResponse._exportId,
      "flowId": invokeFlowResponse.message._flowId,
      "endDate": invokeFlowResponse.endDate
    }

    response.statusCode = 200;
  } catch(e) {
      invokeFlowResponse = JSON.stringify(e);
      response.statusCode = 400;
  } 

  // Create body response
  response.body = output;
  return {
    statusCode: response.statusCode,
    headers: { },
    body: response.body
  }
}

Similarly, you can replace the reference to the flow object by a reference to the export or import objects to run an import or export instead.

After you save your script, this is how the API page will look like. Note the public URL generated for your API before you save & close the page.

Step 3 – Create a Token

Next, you need to secure your API by creating a token. Head to the “API tokens” page under “Resources” tab and hit “Create API token” at the top right of the page

Populate the API token info such as the name, validity, and permissions of the token. Then save & close.

You will be redirected to the list of already created API tokens. Click “Show token” for your API and copy your token so that you can use it in the next step, while invoking the API

Step 4 – Invoke the API

Finally, all you need to do now is invoke the API. I’m using Postman for that. You just need to use the API public URL generated for you, and in the Authorization section set the authorization to Bearer token and use the token you generated in the previous step. Here’s a sample call to the API with the data we set to return from the API in the script

Conclusion

Although Celigo is pretty much targeted around data synchronization between different applications, however, you can still invoke and create APIs in the platform. Just note that these APIs offer a means to run your flows, imports, and exports, rather than being a fully fledged APIs that can run a complete workflow then return the results of the workflow as part of the API response.