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 using the Commerce API to connect with Shopify. Currently, the Commerce API supports various models including Customers, Orders, Products, etc. However, if the ISV wants to access Shopify's GET /admin/api/2023-10/draft_orders.json endpoint, without Passthrough APIs, the ISV would be out of luck as this endpoint is not mapped to 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 --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 --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": "[email protected]",
    "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.

{  
    "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 all connectors in Unified API.