My API basics

Client applications can synchronously invoke custom HTTP endpoints, known as My APIs, to execute script in integrator.io.

To make a request to an integrator.io My API endpoint from another app, you must set up all of the items below:

1. A My API object, complete with…
   1. JavaScript written to call integrator.io API runtime functions.
   2. Error handling and a response to the calling application (demonstrated in the examples).
   3. A unique endpoint URI containing an app ID for the My API object.
      1. Optionally, integration with ShipWorks that generates a separate endpoint URI.
2. A retrieved bearer token that the calling app will pass to identify its authorization.

Then, you can call the My API object’s code from your existing applications. You will find My API useful when you need to build integrations and integrator.io needs to be the receiver of the requests (instead of the initiator of the requests). For example, you can build a My API when a webstore needs to ask NetSuite to compute pricing and integrate that information in real time. 

Note: My API functions can be used to invoke the resources within a custom integration. However, they cannot be used on any flow or item within an Integration App.

The integrator.io API is rate limited using a leaky-bucket algorithm with a bucket size of 1,000 and a fill rate of 300 tokens every second, which allows you up to approximately 1,080,000 requests per hour.

Create a My API object

In order to access My APIs and their associated tokens, you must enable Developer mode and be an account owner. Then, in the Resources menu, you can create, modify, or delete the My APIs.

To create a My API:

1. Navigate to Resources > My APIs.
2. Click + Create My API at the upper right.
3. Enter the General settings, as described below. (There are also optional Advanced settings for integrating with ShipWorks.)
4. Click Save & close to commit the changes and return to the list of My APIs.

Name (required): Provide a meaningful moniker so that you can easily reference it from other My APIs in the list on this page and when creating API tokens.

Description (optional): Enter details of the problem you are solving and how the My API works. Be sure to highlight any nuances that another user – or yourself – making changes later might want to know.

Scripts (required): Select a script from the list that you’ve already written, or click the + icon to start writing your own code in the Create script form. The easiest way to start from scratch is to select the Handle request function stub, which fully documents the options passed to the function and the expected response object:

Tip: Within your script logic, you can support any content-type (such as JSON or XML) or any HTTP request method (GET, PUT, POST, and so forth), and you can invoke any number of external APIs. The built-in JS runtime module contains several objects and functions that you can script to automate common integrator.io tasks.

Function (required): Enter the name of the function that will get called when a request is sent to the My API. Although you may write as much code as you require, only the single entry point specified here is initially called and receives any data passed in the HTTP header and body.

The name of the function in the default Handle request stub is handleRequest. If you used a different name, you may find it easiest to click the icon to open the script for editing and copy the exact name (without parentheses) for this Function setting.

Default handleRequest script

/*
* handleRequest function stub:
*
* The name of the function can be changed to anything you like.
*
* The function will be passed one 'options' argument that has the following fields:
* 'method' - http request method (uppercase string).
* 'headers' - http request headers (object).
* 'queryString' - http request query string (object).
* 'body' - parsed http request body (object, or undefined if unable to parse).
* 'rawBody' - raw http request body (string).
*
* The function needs to return a response object that has the following fields:
* 'statusCode' - http response status code (number).
* 'headers' - http response headers overrides (object, optional).
* 'body' - http response body (string or object).
* Throwing an exception will signal an error.
*/
function handleRequest (options) {
 return {
 statusCode: 200,
 headers: { },
 body: options.body
 }
}

Advanced settings: ShipWorks authentication

Continuing in the Create My API pane: Advanced settings

Enable ShipWorks authentication (optional): Check this box if you will be receiving HTTP requests from ShipWorks, so that integrator.io will provide the required logon credentials.

Username (enabled & required, only for authentication): Enter the ShipWorks username that you provided during the store setup.

Password (enabled & required, only for authentication): Enter the ShipWorks password that you provided during the store setup. Multiple layers of protection are in place, including AES 256 encryption, to keep your password secure. When editing this form later, you must enter this password again; it is stored only for a saved My API.

Copy your unique endpoint URI

When you invoke the My API from another application, you must provide the unique endpoint URI, which is displayed in My APIs. 

Click the name of a My API in the list or choose Actions… > Edit My API. Then, click Copy URL to add the contents to your clipboard.

Sample unique My API endpoint

Sample unique My API endpoint, optional ShipWorks variant
Provide the username and password in your request for authentication – no bearer token is required

These values are also displayed earlier when you click Save in the Create My API pane, instead of closing when done.