Articles in this section

JavaScript API basics

Note

JavaScript APIs were formerly known as "MyAPIs".

JavaScript 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 JavaScript 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 the JavaScript API. JavaScript API also uses synchronous requests to invoke exports and imports. Flows invoked from your JavaScript API script don't guarantee immediate flow execution. This function ensures that the flow is added to the execution queue. JavaScript API logs, errors, and dashboards are not updated. JavaScript API is also the only integrator.io resource that supports returning a response in a format other than JSON.

Note

JavaScript 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 JavaScript 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 JavaScript API(s) 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.

360073567672-my-apis-cloud.svg

Your cloud or on-premise app sends a JavaScript 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. 

JavaScript 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 JavaScript API endpoint, you’ll need to create a JavaScript API(s) and get a bearer token. Then, you can call the JavaScript 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.

Create a JavaScript API object

You must be an  account owner or administrator. Then, you can create, modify, or delete the JavaScript API in the Resources menu.

resources_api.png

To create a JavaScript API(s):

  1. Navigate to ResourcesAPIs.

  2. Click JavaScript tab+ Create APIJavaScript on the upper right-hand side of the screen.

    JavaScript_APIs.png
  3. Enter a unique Name and detailed Description of how the JavaScript API works. Be sure to highlight any nuances you or another user making changes might want to know later.

    360064229792-my-apis-3.png

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 (pencil.svg) 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.

360064229832-my-apis-4.png

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 JavaScript API(s); 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 pencil.svg icon to open the script for editing and copy the exact name (without parentheses) for this Function setting.

JS_API_Advanced.png

Continuing in the Create API pane: Advanced settings 

  • 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 JavaScript API.

Copy your unique endpoint URI

Click the name of a JavaScript API in the list or choose Actions (...)Edit JavaScript API. Then, click Copy URL to add the contents to your clipboard.

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

Invoke_URL_highlight.png

Sample unique JavaScript API endpoint 

360064257192-my-apis-7.png

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