Unified Pass Through

Introduction

Welcome to the guide on the Unified Pass Through feature for our Unified API! Our Unified API is designed to simplify your integration with various SaaS providers by providing a single, cohesive interface. However, we understand that sometimes you may need to send additional data that isn’t included in our standard setup. That's where our Pass Through feature comes in.

The Unified Pass Through feature is a powerful addition to the Unified API, offering enhanced flexibility and control over the data you send in your API requests. With Pass Through, you can add or override data in your requests to meet the specific requirements of different SaaS providers. This ensures that you can fully customize your interactions with each service, even if the needed data is not part of our standard API model.

Purpose of the Guide

This guide aims to provide a comprehensive understanding of the Pass Through feature, including its benefits, key features, and detailed implementation instructions. Whether you are a developer looking to integrate this feature into your applications or a business user wanting to understand its potential, this guide will equip you with the knowledge needed to effectively utilize Pass Through.

Let's dive in and explore how the Pass Through feature can enhance your integration capabilities with our Unified API.

Understanding the Pass Through Feature

What is Pass Through?

The Pass Through feature is an enhancement to our Unified API that allows you to add or override data in your API requests. This feature provides the flexibility to include any extra information that might be required by the SaaS provider you're connecting to, even if it's not part of our standard model.

Definition and Purpose

Definition: Pass Through enables you to inject custom data into your API requests, tailoring them to meet specific needs of various services.
Purpose: The main purpose of Pass Through is to offer greater flexibility and control over the data transmitted through the Unified API, ensuring you can accommodate the unique requirements of different SaaS providers.

Use Cases and Examples

Custom Data Requirements: When a service requires additional data that is not included in the standard API model, you can use Pass Through to add this data.
- Example: A CRM service may require a specific custom field in the request that is not typically included in the standard integration.
Overriding Default Data: If you need to override existing data in the request, Pass Through allows you to specify the new values.
- Example: Updating the default currency from USD to EUR for a particular transaction.
Complex Data Structures: For services that require nested or complex data structures, Pass Through can handle these requirements seamlessly.
- Example: Sending a nested JSON object with detailed customer information to an analytics service.

Key Features

Service-Specific Customization

Explanation and Benefits: Pass Through allows you to customize the data sent to each service individually. This ensures that each service receives exactly the information it needs without affecting other services.
Example Scenarios:
- Sending additional user metadata to a marketing service while keeping the standard data model for other services.
- Customizing the format of date fields for a specific financial service.

Simple Additions

How to Add Extra Data: You can easily add extra data to your API requests using Pass Through. This can be a single value, a list, or more complex nested information.
Example Scenarios:
- Adding a promotional code to an e-commerce transaction request.
- Including additional contact information in a customer profile update.

Advanced Customization

Navigating to Specific Points in Nested Objects/Arrays: Pass Through supports advanced customization by allowing you to navigate to specific points within nested objects or arrays in your API request. This enables you to set, override, or nullify any value with precision.
Example Scenarios:
- Tax Specification for Invoice Items: Suppose there is a tax specification required for a specific type of invoice item that is only supported by Quickbooks. With Pass Through, you can navigate to the specific invoice item within a nested array and add the necessary tax information.
- Selective Data Modification: For complex data structures, such as customer profiles with multiple nested attributes, you can target specific fields within the profile to update or nullify certain values based on the requirements of the service you are integrating with.
- Conditional Overrides: Implement logic to conditionally override data within nested structures. For instance, if certain fields need to be updated only when specific conditions are met, Pass Through allows you to apply these changes accurately.

By leveraging these key aspects of the Pass Through feature, you can ensure that your API requests meet the exact requirements of each service, even when dealing with intricate data structures or service-specific business logic.

Implementation Details

The Pass Through feature provides several methods to customize your API requests. This section will cover the details of these methods, starting with simple pass through.

Simple Pass Through

Simple pass through extends the request body with additional data specified in the

extend_object

, handling various types of data structures seamlessly.

Behavior: Directly extends the request body with the specified data in
```
extend_object
```
.
Handling Undefined or Empty Data: Manages cases where
```
pass_through
```
is undefined, an empty object, or an empty array gracefully.
Nested Objects and Arrays: Supports complex structures, including nested objects and arrays.
Key Overrides: Allows existing keys in the request data to be overridden with new values, including
```
null
```
, strings, objects, and arrays.

Examples:

Basic Extension:


{
  "foo": "bar",
  "pass_through": [
    {
      "service_id": "salesforce",
      "extend_object": {
        "baz": "qux"
      }
    }
  ]
}

Result:


{
  "foo": "bar",
  "baz": "qux"
}

Removing Data:


{
  "foo": "bar",
  "baz": "qux",
  "pass_through": [
    {
      "service_id": "salesforce",
      "extend_object": {
        "baz": undefined
      }
    }
  ]
}

Result:


{
  "foo": "bar"
}

Adding Objects:


{
  "foo": "bar",
  "pass_through": [
    {
      "service_id": "salesforce",
      "extend_object": {
        "baz": {
          "qux": "quux",
          "corge": "grault"
        }
      }
    }
  ]
}

Result:


{
  "foo": "bar",
  "baz": {
    "qux": "quux",
    "corge": "grault"
  }
}

Set a Property to null:


{
  "foo": "bar",
  "baz": "qux",
  "pass_through": [
    {
      "service_id": "salesforce",
      "extend_object": {
        "baz": null
      }
    }
  ]
}

Result:


{
  "foo": "bar",
  "baz": null
}

By utilizing the

extend_object

key within the

pass_through

array, you can seamlessly extend or override your API request data to meet the specific needs of different services. This method ensures flexibility and precision in handling various data structures.

JSONPath Pass Through

The JSONPath pass through feature uses JSONPath expressions to target specific parts of the request body for modification. This allows for precise and advanced customization.

Behavior: Uses JSONPath expressions to inject key-value pairs into the request body.
Key Injection: Inserts key-value pairs even if the path does not initially exist.
Array Handling: Applies value overrides within arrays, either selectively or for all items.
Conditional Overrides: Supports JSONPath filters to conditionally overwrite items.
Error Handling: Manages cases where JSONPath filters do not match any items or are poorly constructed.

Examples:

Basic Key Injection:


{
  "store": {
    "book": [
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      {
        "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      }
    ]
  },
  "pass_through": [
    {
      "service_id": "testService",
      "extend_paths": [
        {
          "path": "$.store.book[*].price",
          "value": 20
        }
      ]
    }
  ]
}

Result:


{
  "store": {
    "book": [
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 20
      },
      {
        "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 20
      }
    ]
  }
}

Conditional Overrides Using Filters:


{
  "items": [
    {
      "id": 1,
      "value": "originalValue",
      "type": "A"
    },
    {
      "id": 2,
      "value": "originalValue",
      "type": "B"
    }
  ],
  "pass_through": [
    {
      "service_id": "testService",
      "extend_paths": [
        {
          "path": "$.items[?(@.type=='A')].value",
          "value": "newValueForTypeA"
        }
      ]
    }
  ]
}

Result:


{
  "items": [
    {
      "id": 1,
      "value": "newValueForTypeA",
      "type": "A"
    },
    {
      "id": 2,
      "value": "originalValue",
      "type": "B"
    }
  ]
}

Injecting a New Property:


{
  "items": [
    {
      "id": 1,
      "value": "originalValue"
    },
    {
      "id": 2,
      "value": "originalValue"
    }
  ],
  "pass_through": [
    {
      "service_id": "testService",
      "extend_paths": [
        {
          "path": "$.items[?(@.id==1)].details",
          "value": {
            "description": "Detailed information",
            "status": "active"
          }
        }
      ]
    }
  ]
}

Result:


{
  "items": [
    {
      "id": 1,
      "value": "originalValue",
      "details": {
        "description": "Detailed information",
        "status": "active"
      }
    },
    {
      "id": 2,
      "value": "originalValue"
    }
  ]
}

By utilizing the

extend_paths

key within the

pass_through

array, you can navigate to specific points within your JSON request body and modify them as needed. This allows for precise and flexible customization of your API requests.

Conclusion

The Pass Through feature is a powerful enhancement to our Unified API, providing unparalleled flexibility and control over your API requests. By enabling you to add or override data through simple additions or advanced JSONPath expressions, Pass Through ensures that you can meet the unique requirements of each SaaS provider you integrate with. Whether you need to add custom fields, handle complex nested data, or apply precise modifications to specific parts of your requests, the Pass Through feature is designed to handle it all with ease.

We encourage you to leverage the new Pass Through feature to optimize your integrations and take full advantage of its capabilities. By customizing your API requests to suit the specific needs of different services, you can enhance the efficiency and effectiveness of your interactions with various SaaS providers. This flexibility can lead to more robust integrations, improved data accuracy, and ultimately, a better experience for your end-users.

If you have any questions or need further assistance with implementing the Pass Through feature, our support team is here to help. Please feel free to reach out.

Thank you for choosing our Unified API. We look forward to seeing how you will use the Pass Through feature to enhance your integrations.