Passthrough API

Passthrough APIs are designed to afford an ISV flexibility when accessing endpoints not directly supported within any of Alloy's connectors. With Passthrough API, you can also access the raw data returned by the endpoints supported by Alloy.

Example Scenario

Consider an ISV that has built an integration to Shopify using Alloy. This ISV is now looking to extend the functionality of its platform for its end-users. To do so, the ISV requires access to Shopify's GET /admin/api/2023-10/draft_orders.json endpoint. Without Passthrough API, the ISV would be out of luck as this endpoint is not supported within Alloy’s Shopify connector.

Fortunately, Passthrough API 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/2024-03/passthrough?credentialId={{END_USER_SHOPIFY_CREDENTIAL_ID}}' \
--header 'Authorization: Bearer {{YOUR_API_KEY}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "method": "GET",
  "path": "/admin/api/2023-10/draft_orders.json",
  "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. /admin/api/2024-04/draft_orders.json)
• 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 example below uses the Shopify API to create a new customer using Passthrough APIs. Note that the Passthrough API only accepts POST requests.

cURL

curl --location 'https://embedded.runalloy.com/2024-03/passthrough?credentialId={{END_USER_SHOPIFY_CREDENTIAL_ID}}' \
--header 'Authorization: Bearer {{YOUR_API_KEY}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "method": "POST",
  "path": "/admin/api/2023-10/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 Shopify example, once invoked, the Passthrough API uses the underlying credential you supplied (via the credentialId). The passthrough API will then return the raw data from Shopify's /admin/api/2023-10/draft_orders.json endpoint as seen below. Alloy Unified API will return the relevant headers, statusCode, and data.

javascript

{
    "request": {
        "headers": null,
        "method": "GET",
        "path": "/admin/api/2023-10/draft_orders.json",
        "data": null,
        "params": null
    },
    "headers": {
        ...
        // Detailed response headers
    },
    "statusCode": 200,
    "data": {
        ...
        // Parsed raw data from Shopify
    }
}

Connectors Supported by Passthrough API

Passthrough API is currently available for the following connectors:

• Shopify
• Meta Ads
• BigCommerce
• WooCommerce
• Slack
• Klaviyo
• Gorgias
• Postscript
• Recharge
• Attentive
• Asana
• Inverterate
• Stamped.io
• Yotpo Loyalty