Thank you for your review @RAMKUMAR RAMALINGAM
In our previous blogs, we have covered how to develop a connector using IBM CDK. In this article, let’s go through a list of capabilities that makes a connector intuitive for users. As a connector developer, you might have a good knowledge on the target application for which the connector is built, however the users of your connector might not have the same knowledge of yours, so it’s important to build a connector that is consumable for all users.
Connectors are building blocks of an Integration platform. They provide seamless integration with the applications in a consistent manner. In this article you will learn what it takes to build a connector that is intuitive for all users, and how CDK helps you to build such a connector. Let’s go over them in detail.
Define display names and descriptions
Display names and descriptions for key properties are crucial. Display name shall help user to easily find what they are looking for and descriptions shall convey the complete information of the item. Do not assume that your users are aware of each item of the application.
Here are some of the important properties that need detailed and precise descriptions:
1. Connector description – Define the use of the connector at high level and any targeted domain or subdomain of the application.
2. Connection properties – Explain in detail each connection properties.
3. Action – Define the functionality the action performs in detail with any edge cases.
4. Mandatory request properties – Explain each property in detail with examples and default value.
Ensure each property has a proper display name and description. Cryptic property names or JSON payload names are difficult to understand. Keep the display name concise and understandable. Ensure that property display names are consistent with the display names in the application UI.
Provider proper display name for the action to convey the action it performs on the application. Having proper display names and descriptions reduces a good number of support tickets.
Define object relationships
You need to identify and define the relationship between objects. Most common relation is parent-child relation. In this relation, in order to perform some action on the child you need to pass in the parent id. The general ReST standard for such kind of API would looks like this - `/parent/{parentId}/child`. There are many examples of parent-child relations in the real world, for example - an issue is a child of a repository, an employee object is a child of a department, an address object is a child of a contact, etc,.
In App Connect, these relations are first class entities. App Connect provides advance experience for such relations. Look at how connectors relations are showed on App Connect designer UI. This will greatly enhance the user experience of the connector.
You can easily define the relationship between actions easily in the CDK. CDK allows you define relationship on the path parameters in your ReST API URL.
In the below example, the "create an issue" action has ,two path parameters. As an issue belongs a repository, we can define a relationship between issue and repository.
Define pagination strategy
Connector shall be capable of retrieving a large number of records from the application. These actions are used in the data copy scenarios where the data from one application gets moved to another applications. Most of the applications provide GET APIs that can retrieve records from the application in the paginated manner. A smart connector should understand the pagination strategy and implement the same.
IBM Connector Development Kit allows you define any of 3 most commonly used pagination strategies while defining the action.
Keep your actions simple
Make your connector actions simple to use. Restrict request properties to a minimal set that satisfies most of the use cases. Move not commonly used properties to the advance mode. Have mandatory and commonly used properties at the top in a specific order. Remove response properties that are not useful to users. Define relationship wherever possible. Have proper display name and description for your action and all its properties.
Keep your connector simple
Keep your connector simple with limited actions. If targeted application is huge (having a lot of APIs) you can develop multiple connectors targeting specific area of the application. For example, if you are developing a GitHub connector, instead of developing a big GitHub connector with 10s of actions. You can build multiple connectors like GitHub Issue management connector, GitHub Pull Request Connector, etc,.
Summary
It is important that you build a connector that is easy to use, robust, and self-explanatory. CDK has all the options that allow you to build a first-class connector that is consumable by all users. Do not assume that your users know everything about the application.