Passthrough APIs

Passthrough APIs are designed to afford an ISV flexibility when needing to access endpoints not directly supported by the Alloy's Unified API.

Example Scenario

Consider an ISV using the Accounting API to connect with NetSuite. Currently, the Accounting API supports various models including Accounts, Bills, Invoices, etc. However, if the ISV wants to access NetSuite's GET /purchase-orders endpoint, without Passthrough APIs, the ISV would be out of luck as this endpoint is not mapped to the Unified API.

Fortunately, Passthrough APIs solves this problem. With Passthrough APIs, the ISV can specify the raw http path to make a call to using the end user's underlying authentication.

Implementation

Making a Request

To forward a request, use the following curl command:

cURL

curl --location 'https://embedded.runalloy.com/2023-12/one/forward?connectionId={{YOUR_CONNECTION_ID}}' \
--header 'Authorization: Bearer {{YOUR_API_KEY}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "method": "GET",
  "endpoint": "/purchase-orders",
  "body": null,
  "query": null,
  "extraHeaders": null
}
'

Parameters Explained

• method: (required) The HTTP method of the Passthrough APIs you're trying to make (i.e. GET, POST)
• path: (required) The relative path of the endpoint to call (i.e. /purchase-orders)
• extraHeaders: (optional) Any headers to send along with the request. Must be in a stringified JSON format. Pass null if not sending anything.
• query: (Optional) Any query parameters for the request. Pass null if not sending anything.
• body: (Optional) Any body parameters for the request. Must be in a stringified JSON format. Pass null if not sending anything.

More Advanced Example:

The below example uses the Shopify API to create a new customer using Passthrough APIs.

cURL

curl --location 'https://embedded.runalloy.com/2023-12/one/forward?connectionId={{YOUR_CONNECTION_ID}}' \
--header 'Authorization: Bearer {{YOUR_API_KEY}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "method": "POST",
  "endpoint": "/customers.json",
  "body": {
    "customer": {
    "id": 1073339469,
    "email": "steve.lastnameson@example.com",
    "accepts_marketing": false,
    "created_at": "2023-12-11T10:28:27-05:00",
    "updated_at": "2023-12-11T10:28:27-05:00",
    "first_name": "Steve",
    "last_name": "Lastnameson",
    "orders_count": 0
    }
  },
  "query": null,
  "extraHeaders": null
}
'

Receiving a Response

Returning to our NetSuite example, once invoked, the Passthrough API uses the underlying credential you supplied (via the connectionId). The passthrough API will then return the raw data from NetSuite's purchase-orders endpoint as seen below. Alloy Unified API will return the relevant headers, statusCode, and data.

JavaScript

{
    "request": {
        "headers": null,
        "method": "GET",
        "path": "/purchase-orders",
        "data": null,
        "params": null
    },
    "headers": {
        ...
        // Detailed response headers
    },
    "statusCode": 200,
    "data": {
        ...
        // Parsed raw data from NetSuite
    }
}