My API basics

My APIs are custom HTTP endpoints built directly in integrator.io, which client applications can invoke. They are simply custom-made endpoints. Usually, integrator.io initiates a transfer between applications; however, with My API, integrator.io receives a request from an external application to trigger a flow, export, or import. The external application sends a request and receives a response from My API. My API also uses synchronous requests to invoke exports and imports. Flows invoked from your My API script don't guarantee immediate flow execution. This function ensures that the flow is added to the execution queue. My API logs, errors, and dashboards are not updated. My API is also the only integrator.io resource that supports returning a response in a format other than JSON. 

Note: My API functions can be used to invoke the resources within a custom integration. However, you can’t use them to invoke Integration Apps or resources within Integration Apps.

With My API, integrator.io receives a request from Shopify to trigger an import or export that makes NetSuite perform a task. For example, Shopify can send a My API request that invokes an import to create an invoice in NetSuite. In this case, integrator.io didn’t initiate the request; they received it from Shopify.

Your cloud or on-premise app sends a My API request to integrator.io, which triggers a script that invokes a flow, export, or import. The response is sent back to your app as required by the script.

My API is useful when initiating integration tasks like

• Syncing a newly released Empower change order into NetSuite.
• Getting ShipWorks order information from external systems on demand.
• Returning an immediate response to a Slackbot (via synchronous processing).

Rate limits

Before you can trigger a My API endpoint, you’ll need to create a My API and get a bearer token. Then, you can call the My API from your desired applications.

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, allowing up to approximately 1,080,000 requests per hour.

Execution time limits

After triggering a My API endpoint, certain execution time limits are triggered:

• CPU time limit —The CPU time limit determines the time it takes to run the JavaScript code. It is limited to 4 seconds per script invocation.
  • Error message – Script did not terminate within time limit.
• integrator.io time limit – The integrator.io time limit determines the time it takes to run an integrator.io API call. It is limited to 2 minutes per integrator.io API call within a script.
  • Error message – HTTP callout did not complete within time limit.
• My API time limit – The My API time limit determines how long the My API script will run if the first two time limits are not reached. It is limited to 2 minutes for each /apis/:_apiId/request API call.

Create a My API object

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

To create a My API:

1. Navigate to Resources → My APIs.
2. Click + Create My API on the upper right-hand side of the screen.
3. Enter a unique Name and detailed Description of how the My API works. Be sure to highlight any nuances you or another user making changes might want to know later.

Scripts (required)

Select a script from the list that you’ve already written, click the + icon to start writing your own code in the Create script form, or modify an existing script using the pencil () icon. If you’re starting from scratch, insert a function stub that provides all the required fields for the request and response. Note that if you modify a script in one location, it is modified everywhere.

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

Function (required)

Enter the name of the function. This is the function name that gets called when a request is sent to My API; although you can write as much code as you need, 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.

Continuing in the Create My API pane: Advanced settings

1. Enable ShipWorks authentication (optional): Check this box if you will be receiving HTTP requests from ShipWorks, so that integrator.io provides the required login credentials.
   1. Username (enabled & required, only for authentication): Enter the ShipWorks username you provided during the store setup.
   2. Password (enabled & required, only for authentication): Enter the ShipWorks password 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

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

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

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