ITENTIAL ADAPTERS TECHNICAL RESOURCE
Adapter Builder
Input Limitations
Swagger / OpenAPI
The Adapter Builder accepts Swagger and OpenAPI documents. However, there can be issues in these documents that can have a negative impact on the Adapter Builder.
Some of the issues we have found:
- Certain errors can result in not being able to build an adapter, while others can cause various issues with the adapter that is generated.
- The use of certain parameters can result in the adapter not linting clean.
- The use of certain parameters as well as unsupported data types can result in the adapter not testing clean. Some data types are not supported by ajv or javascript.
- Missing operationIDs can cause long complex method names.
- Nested references, especially the ones that loop, can cause issues where validation of the Swagger file by the Adapter Builder gets into an infinite loop and leads to an excessive number of minutes (5+) for the adapter to build. In addition, the adapter may be missing input and output data.
How can I make the Swagger (OpenAPI) document better?
- If you are having issues, the first thing to do is validate the Swagger document using a site such as this one: https://editor.swagger.io/ . Validation of the Swagger specification in a document can help to address several reported issues.
- If the adapter that is built does not lint or test clean, report it to the Itential Adapters Team and let us help troubleshoot and address the issue so that future adapters do not have the same issues.
- If you find the adapter has a lot of long complex calls, determine if it is worthwhile to add operationIDs to the Swagger document so that the methods name will be more apparent.
- If it seems like the Adapter Builder is hanging, give it time and see if it eventually completes (we have seen it take 8-10 minutes when there is nested references). If this happens, you may want to review the references and clean them up. This should result in a faster build and ensure that the input and output data is better defined in the adapter.
Postman Collections
The Adapter Builder accepts Postman Collection documents. However, these documents can vary without bound. Bad practices can also lead to many issues.
Some of the issues we have found:
- Certain errors can result in not being able to build an adapter, while others can cause various issues with the adapter that is generated.
- The use of certain parameters can result in the adapter not linting clean.
- The use of certain parameters as well as unsupported data types can result in the adapter not testing clean. Some data types are not supported by ajv or javascript.
- Undefined methods can cause long complex method names as they will be derived from the path.
How can I make my Postman Collections better?
- Clearly define what is being done in each request.
- If the adapter that is built does not lint or test clean, report it to the Itential Adapters Team and let us help troubleshoot and address the issue so that future adapters do not have the same issues.
- If you find the adapter has a lot of long complex calls, determine if it is worthwhile address how you define the requests so that the methods name will be more apparent.
WSDL
SOAP Systems generally come with a WSDL. At times in the past the Adapter Builder accepted WSDLs. Since there are other systems that will convert a WSDL to Swagger, we decided to forgo the support of WSDLs.
If you have a WSDL and want to build an adapter, follow this process:
- Go to APIMatic (https://www.apimatic.io/). You can get a free trial but even after the trial, you will have the ability to transform APIs.
- If you have never used APIMatic, sign up for a free trial. If you have used it, log in.
- On the dashboard, click “Transform API”.
- Upload the file by clicking “Choose File” or provide the URL for the API document.
- Select the format you want. The ideal formats for the Adapter Builder are: OpenAPI/Swagger v2.0 or v3.0 in JSON.
- Click “Convert”.
- You can use other tools that you might be aware of instead of APIMatic.
- Note, if the WSDL references other WSDL files, you will need to combine them so that a complete WSDL is provided. If the tools cannot get to the necessary information (references) they cannot properly convert the API for you.
Pre-Install Checklist
Important Information to Know
- Each step of the adapter attempts to gather information about the adapter and the system it is connecting to, such as :
- Adapter ownership
- System integrating with
- Authentication
- Determining if system is up
- Other properties
- Deciding what API calls to use
- Building use cases
- While the Adapter Builder attempts to make it easy by defaulting much of this information, it’s important to know that accepting all the defaults will result in you doing more work later. For example:
- Accepting the default authentication will mean that when you deploy the adapter you will have to configure the authentication method. This will mean updating several files and adapter properties.
- Using the default namespace when you want a custom namespace will require you to change the namespace in many files.
- Naming the adapter incorrectly can result in you needing to change the adapter name in several locations.
Important Information to Review and Complete
- Know how to change the data you enter.
- Many of the fields provide information that tells you how to change the data after the adapter is built.
- Review the information that is provided to you.
- For the information involved in the API call (e.g. protocol, host, base path, version, etc.), the Adapter Builder shows you the current API call as it would be made. Verify that information is correct before proceeding.
- Determine how API calls can be completed to:
- Give you 100% API coverage.
- Reduce the size of the adapter by only selecting the API calls you know you will use.
- Building use cases can be very useful when integrating with IAP. Adapter use cases can provide workflows that can be:
- Used to test the adapter.
- Enhanced to build automations.
Installation
Guidelines and Best Practices
- Follow the instructions that tell you how to install the adapter.
- Make sure to lint and test the adapter.
- The goal of Adapter Builder is 0 lint issues
- The goal of Adapter Builder is 100% of tests passing.
- Sometimes there are issues, and this will not be the case. For example:
- May have keywords as parameters.
- There may be a bug in the way something was converted.
- If there are issues it will save time if you find them before integrating.
- Know that authentication and integration may take some time to get working.
- Review the Adapter Authentication and Adapter Troubleshooting resources for more information.
Adapter Support
For help with any adapter changes:
- Create a ticket (ISD, IPSO or ADAPT).
- You can work the ticket or allow the Itential Adapter Team to verify if the new authentication capability can be supported.
- Once all changes are made, update the adapter-utils dependency in your adapter or run the adapterMigrator.
To update your adapter-utils dependency:
- Change the version in the package.json dependencies.
- rm –rf node modules
- rm package-lock.json
- npm install