Pre-Development Considerations
Pre-Development Considerations
What do I need to build a connector?
You will need intermediate C# development skills and a suitable API. The connector can be thought of in part as an API client, in which the API endpoints correlate to the data objects and actions that will be defined in the connector and thereby made available to integrations and flows on the platform.
API Evaluation
Performing an API evaluation before developing a connector will help to determine if an existing API is fit to build a connector with or needs enhancement before connector development may begin. If developing a new API for a product, this exercise can provide an inventory of the API endpoints and methods that will need to be developed.
API Type
In general, an HTTP or REST API will be used for building a connector. If needed or preferred, other types of API may be employed, for example GraphQL, RPC, or SOAP. In this event, please let us know.
The App Xchange team is currently working to enable using asynchronous events (e.g., Kafka streams) or webhooks for SDK-built connectors. This page will be updated to include further details when available.
The topics below focus primarily on an HTTP/REST API. Equivalent functionality would be needed for any other type of API used.
Authentication
Integrations on the platform depend on executing flows on behalf of users without their direct intervention, and therefore non-interactive API authentication is preferred with the following authentication types being supported:
Documentation
OpenAPI ≥ 3.0 is generally preferred for HTTP/REST API documentation. If well prepared, it can facilitate an informed evaluation of the API a connector will leverage; but it is not a requirement for building a connector on the platform.
The connector SDK will automatically prepare OpenAPI documentation for the connector API (not to be confused with the API of the connected product or application). This documentation will be available to users building integrations with the connector.
Endpoints
The API should include endpoints and HTTP verbs (or methods) correlating to the resources (data objects) and operations (actions) needed to build integrations with the connected product or application.
For example, if an integration would depend on the ability to get a list of projects from a backend database, a GET /projects endpoint would likely be needed. To get data on an individual project, an endpoint like GET /projects/{id} could be used. POST, PATCH, PUT, and DELETE operations will typically be needed for creating, updating, and deleting entries.
In practice, this will largely be a matter of evaluating the integrations for which a connector will be used and confirming if the API facilitates them. The connector may provide initial use cases to begin with and can be expanded upon later as needed.
It may be useful to prepare a list of these data objects to confirm that any endpoints and methods needed are in place before developing the connector. Please view our Integration Design Guide for a more in-depth explanation of how to approach building integrations on the App Xchange platform.
Filtering and Pagination
The API endpoints should include any parameters needed to filter and/or edit the data being queried or created.
In particular, filtering should include the ability to query for changed data based on a date or time frame and pagination to limit the amount of data transferred per call.
Data Strategy
Before developing a connector, you should ideally have an initial use case as described in the Integration Design guide. While your actual connector should be agnostic with regards to eventual integrations, a minimum viable product state should support actual business use as the connector may be extended later to provide new data and capabilities over time.
To that end, avoid hard coding values or data mapping. Good choices have data objects and actions that closely map your API and are as general as possible.
Your design should avoid future breaking changes - even in the development and testing phase, we want to confirm your intentions before deploying. Breaking changes would include changing the module key, adding or changing required data object properties, changing (vs adding) to the data object key, or removing object properties entirely.
The train of thought to use is: if the schema changes in a way that would result in any already existing payloads (queued action steps for example) to generate a payload that would not pass schema validation, then that is a breaking change. Therefore you should also make “required” now anything you know will be required later if possible, so incomplete data does not get generated on the platform.
Connector Requirements
App Xchange code approval focuses on safety and avoiding security and performance risks, not optimization or design. It is typically the connector builders responsibility to do quality assurance on their connector and confirm that the connector design supports their business requirements.
Connectors that do not meet minimum criteria will not be deployed to the platform, and connectors that do not follow best practices will receive feedback and require specific reasoning before deployment. Further detail on the technical expectations for connectors to be deployed on the App Xchange platform will be available on the SDK documentation pages.