Adapter Builder Input

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.