No connectors? No problem!

TL,DR Wouldn’t it be cool if all these new PAAS/SAAS platforms had a “connector” for building custom “connectors”?

In the low-code/no-code space, development teams implement standard integrations as “plugins” or “connectors” which allows non-technical users to port data from one system to another with limited technical know-how. Some examples of these plugins are the Linx GoogleDrive and Xero plugins or Outsystems DropBox connector.

The terms “connectors” or “plugins” are used interchangeably, and there’s some debate on what exactly defines them. In practice, these refer to pieces of functionality that allow you to send and receive data from your custom system or platform to another. The advantage of these is that different companies specialise in what they’re good at; for example, Xero handles the accounting, Shopify manages the sales and Hubspot can manage the marketing.

However, the issue is that these systems do not natively talk to one another, which leads to your different pieces of data being stored in different formats and scattered across platforms. Typically, this leads to manually retrieving the various parts and reconciling them in spreadsheets of some kind, which defeats the purpose of having these specialist systems.

With the emergence of APIs, these platforms can now programmatically expose your data, allowing you to pull and push the required details as you wish by using “connectors”. These are standard integration functions wrapped in a pretty interface and are typically achieved via an HTTP request to a REST API. However, the end-user only has to configure some inputs and doesn’t view the nitty-gritty details.

Most of the integrations that users are looking to use deal with connecting to major 3rd party platforms such as Microsoft, Google, Xero etc. These connectors allow users to extend those systems functionality and add them into their business logic. The advantage of this is that the developers have taken care of the difficulties in connecting to these systems and handling the various nuances such as authentication, data validation and error handling.

However, a disadvantage is that connectors need to be built by the platform’s in-house development team, and this means that connectors that are high on your priority list might not be a priority for them. Additionally, you have no idea of timelines, and developers often need to design and build these connectors to handle every situation that can take time and is usually overkill.

Finally, these low-code platforms contain other functionality not related to HTTP connectors that are also being developed by the in-house teams, such as API hosting or Database integrations, meaning connectors to your particular platform might fall low on the list of priorities.

Once you’ve decided to go with a particular platform, you may run into the issues mentioned above, and your project may become stalled as you wait for the specific connector to be designed and implemented on the chosen platform.

But Wouldn’t it be cool if these platforms had a “connector” for building custom “connectors”?

Can you customise customisation?

With Linx, you can build custom connectors that suit your needs and aren’t overly complicated. As mentioned earlier, these connectors are just HTTP requests wrapped in a pretty interface that handles the nuances of the different APIs, making life much easier for non-technical users. However, as you build on low-code platforms, you gain technical expertise in the various systems.

If you delve into REST APIs, they’re not as complex and scary as they seem once you get the basics which are pretty much:

• Authentication
• Sending data correctly
• Handling the response data

And that’s pretty much it!

Each system will have its subtle differences, but the approach is the same. Once you’ve figured out how to implement a single request to a chosen API, all the other requests that you want to implement will follow pretty much the same structure in terms of authentication, URLs and data objects.

To give you an example, we recently started developing a sample Linx Solution that integrates with the GitHub REST API. I did this to make my own life a bit easier, managing and automating all our GitHub DevOps for the Linx Sample Library and providing users with a quick way of integrating with their instance of GitHub. And in the spirit of development, why rebuild something that someone else has already built?

So with this in mind, I chose to implement much of the GitHub API as custom Linx functions, which can act as “connectors” that anyone can download and install in their Linx Solution. The advantage of this is that our development team can focus on other technologies.

At the same time, I build out the various “connectors” – and external users can then even extend these connectors to their custom needs without having to go through code reviews, feature requests and testing of every single piece of functionality.

When building a “connector” function, I structure them all the same:

REST endpoint

1. The ‘Endpoint’ contains the particular suffix of the URL to call.

2. The ‘CallRESTEndpoint’ function makes a request to the endpoint.

3. And the ‘ReturnResult’ function returns the result of the HTTP request as an output of the custom Linx function.

To further illustrate, I followed the below flow (I’ve used this API request to the GitHub API as an example):

Check out the API reference documentation

First, you need to know the details of the endpoint you are calling, such as:

• The URL (endpoint) of the operation
• Request authentication
• Request parameters (such as query values, body etc.).
• Response data object.

So, I would go to the particular page of the request, like this one.

Now depending on the level of documentation (some platforms Like GitHub are excellent in this regard), you’re able to set up an HTTP request easily without actually having to make test calls. From the documentation, we can find the method (GET) and the URL to call (/user/repos):

Configure the minimal request structure

With my structure, I can make the value of ‘Endpoint’. This just makes changing the endpoint in future functions much more effortless.

This endpoint ‘/users/repos’ is appended to the main GitHub API URL, ‘https://api.github.com’. Because all endpoints would use this base URL, I can just make it Setting in my Linx Solution:

I can then just reference this Setting value across all my functions. If this URL changes in the future, I can just change it in a single place and have solution-wide effects.

To make an actual call to the API, which requires the method and URL at a minimum:

So at runtime, the above URL property would translate into “‘https://api.github.com/users/repos”.

Add authentication to the request

I now need to configure the authentication achieved by passing an ‘Access Token’ in the request’s header. Of course, now all the requests need the header; however, the value of the ‘access token’ might change or be retrieved as runtime, so I can create an input parameter that will receive this value.

In the CallRESTEndpoint configuration, you can reference this value.

Add any request parameters

Configure any parameters like they are specified in the documentation.

For any needed parameters, I just make them input parameters to my custom Linx function, just like I did with the access token.

I then add these as the actual query parameters of the request, which is simple enough….

Make a test request

We’ve now configured the URL to call, the authentication details and then any query parameters. As it stands, my function will execute the request and return the response as one big string

Not very nice.

To fix this, I’ll create an object that can be used to structure this string.

Import the needed response data structure

With Linx, this is much easier than you would think. Simply copy the whole response

and import it as a custom Linx type

And Linx will then create the needed structure

Now that you have a structure to work with, you can use it to deserialise the response. You can use this structure as an output result of my custom function

And assign the value of the HTTP response to the output of the function

And voila! You now have the response structured as the result of your function

So in practice, you can just drag the reusable function into other pieces of functionality, and it will act like a “connector”. And you can re-use this function as much as you like, wherever you like.

Rinse and repeat

With Linx, once you’ve created a piece of functionality, you’re able to copy that functionality and tweak it to your needs while not having to re-do much of the shared configuration.

Copying this functionality is as easy as ‘Right click -> Copy -> Paste’. And an exact copy of the function will be created, which you can then just tweak accordingly.

For instance, the above example returns all the repositories for the authenticated user. But what if I wanted to retrieve a single repository like it’s specified in this operation of the documentation?

I can just copy the whole ListReposForAuthenticated user and just tweak the process as needed. You will need to change some input parameters (the access token remains as remember you need it for each request)

And alter the endpoint like below

For the actual request, you can remove all the query parameters. The URL and authentication don’t need any changing as this was designed to be generic. Finally, you can change the result of the function to be a single item and not a list.

And you’re done! Don’t forget to change the name of the function to be more descriptive.

You can then follow the same method across all the other endpoints. Because of the generic design in terms of the URL and authorization, adding operations is relatively simple, ending up with a whole range of “connector” functions that anyone can re-use:

These “connector” functions are reusable Linx functions that handle the inputs for the particular requests, makes an HTTP request to the GitHub API using the generic CallRESTEndpoint pre-built function and then parses the response data and returns it as an output of the function.

Thus, each of these functions acts as a “wrapper” for the particular request, and you can just drag and drop the specific function as you wish into your logic:

Take a look at the final GitHub API connectors project or my other Microsoft Graph API connectors project for a similar example.

The post No connectors? No problem! appeared first on Linx.