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 determine if an existing API is fit to build a connector 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 must be developed. Please email xchange_build@trimble.com if you need assistance performing an API evaluation, or have a non-supported API you want us to consider supporting. 

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. The following authentication types are well supported, but custom authentication types may be possible. 

• API Key

• HTTP Basic

• OAuth 2.0

  • Client Credentials

  • Authorization Code

  • Password

Documentation

OpenAPI ≥ 3.0 is generally preferred for HTTP/REST API documentation. It can facilitate an informed evaluation of the API a connector will leverage, but it is not a building requirement for 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 are typically needed for creating, updating, and deleting entries.

In practice, this is 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 and can be expanded upon later as needed.

It is useful to prepare a list of these data objects to confirm that any necessary endpoints and methods 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 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 have an initial use case as described in the Integration Design guide. While your actual connector should be agnostic 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. The App Xchange team  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 make required now anything you know will be required later if possible, so incomplete data is not generated on the platform.

Connector Requirements

App Xchange code approval focuses on safety and avoiding security and performance risks, not optimization or design. You are responsible for performing quality assurance on your connector and confirming that your connector design supports your 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. The SDK documentation pages provide the full technical expectations for connectors to be deployed on the App Xchange platform.