These articles serve as a comprehensive developer's guide for building integrations on the iPaaS.com platform. Together, they outline the platform's conventions, best practices, and technical standards for everything from data modeling and API operations to error handling and performance. These guides are intended for integration developers who are responsible for designing, building, and documenting new integration solutions.
This collection is organized as seven articles:
Integration Development Overview: Lists the initial recommendations and prerequisite checks to review before starting development.
Data Modeling: Explains how to define data model fields, handle CRUD operations, and manage custom fields.
Configuration and Data Storage: Covers configuration methods and data storage options, with a focus on user-facing Presets and internal Persistent Data.
Handling IDs: Provides a detailed guide on defining and managing external IDs, which are essential for linking data records.
Mappings and Transformation Logic: Focuses on data transformation, explaining how to create mappings and use custom functions to manipulate data.
Webhooks: Explains how to configure, receive, and process real-time event notifications (webhooks) from external systems.
Advanced Topics and Best Practices: Covers essential best practices for building a robust integration, such as logging, exception handling, and performance optimization.
As a starting point, the following are items that the team strongly recommends following when developing an integration. While they are not required, they will make it easier for subscribers to use the integration.
Items to check in other systems
Note that while most of these items should have been looked at in discovery, they are worth reviewing before starting on development.
IDs are easily accessible in the UI, URL, or (if neither are available) in the console if available.
Ensure data that is created/updated is visible in other systems
There may be undocumented requirements for fields that are not required by the API (i.e., you can still get a 200), but are needed to make something visible in the UI. For instance, in MailChimp, you can pass in a transaction without a date and get a 200, but without the date, it is not visible in the UI.
Use out-of-the-box APIs wherever possible: In order to ensure maximum compatibility, wherever possible, use the APIs that are supported by the third-party software. This could include following their standard conventions to support their web services. When this is not possible, think through the use case and how you will construct the API to ensure that what you are building is reusable. If you need to build an API or API extension, can this be provided to other clients or published for them to use?
If an extension or non-out-of-the-box endpoint needs to be used, create a preset for it so it is only used when needed/supported.