...
So how do we use it say to create an Atlassian adapter.
| Expand |
|---|
| title | The Goal - A good adapter will have very little code and be easy for the user to extend |
|---|
| It’s better to have a simple ‘incomplete’ adapter that is easily understood and altered by the user than an over elaborate one.
Iguana X is a open system which is intended to allow our customers and do anything. Overly elaborate adapters means that the code is a what we call a Code dump which makes it difficult for other people to adapt and use the code to their own purposes.
This is problem with a lot of Open Source projects.
Sure you have access to the code but that isn’t helpful if it takes months of study to understand it and it the code has many many design flaws that you cannot solve without with years of commitment.
Less is more.| is a library showing how to connect to a system |
|
In Iguana X, an open system, we provide adapters as libraries to connect with various applications. These adapters are intentionally designed to be simple and intuitive, making them easily extendable by users to meet their specific needs. This approach contrasts with the complexity often found in open-source projects and the rigidness of complete platforms like Zapier. Iguana's inclusive environment, featuring a Translator, logging, queuing system, and dashboard, though convenient, requires users to invest effort in learning. Our goal is to empower users with adaptable tools, understanding that no adapter can be universally complete. See: |
| Expand |
|---|
| title | Typically we have an example component which just shows the usage of the library |
|---|
|
The component aims to showcase the library's use, easing the learning process for users to integrate with systems efficiently. It's crafted to enable customers to quickly start without delving deep into documentation or seeking iNTERFACEWARE staff help. Therefore, it doesn't cover every detail of the problem but rather provides a clear direction, setting customers on their own path of exploration and discovery. |
| Expand |
|---|
| title | Adapters will typically be created with the authentication parameters without hardcoded custom fields. |
|---|
|
These parameters should not be hard coded into things like custom fields. This is because our customers may use these adapter libraries in components with others. |
| Expand |
|---|
| title | Often we layer in a 'custom method' which has all the boiler plate code for an say a web API |
|---|
|
For each adapter, we create a custom method to avoid the need for a lot of copy-pasted code. This method contains all the essential code for connecting to a web API, eliminating the repetition of the same code for different API methods. We have one main custom method, with other specific APIs serving as wrappers around it. If we need to access an API method for which we haven't created a specific wrapper, we can simply call this custom method, specify the API path, and provide any necessary parameters. This approach makes using new API methods straightforward and minimizes the need for additional setup. |
| Expand |
|---|
| title | We create a few specific method wrappers for calls that typically use the 'custom method' |
|---|
|
Each specific call does not typically have much code because most of the 'boilerplate' code is in the custom method, and it's nice that each of these methods has help. Doing things this way should make it quite clear to a user how they can extend each adapter. See Setting up help for an object with methods |
| Expand |
|---|
| title | Have some general comments about the nature of the API |
|---|
|
Comments should be concise and straightforward, guiding users on what to do next with the API. For example, in systems like Pipedrive where custom fields use GUIDs, good documentation would explain how to address this issue. The aim is to educate users, not overwhelm them by attempting to solve every problem. |
Implementation Approach:
| Expand |
|---|
| title | Start with a copy of new Custom component |
|---|
|
Let’s use a copy of new Custom component (Create a Component ) and name it ‘Confluence adapter’ |
...