API Gateway connection point

With an API Gateway connection point, you can define a connection from ION to any application with a REST interface that is registered in API Gateway.

To call an API operation, use these scenarios:

  • Send to API
  • Get from API
  • Trigger API

In a data flow, you can use an API Gateway connection point to map an input document to the API request. Send an API response as an output document or map a response to the output document. You can also combine these methods to trigger the required response based on an input document.

To call an API, complete these configuration steps:

  • Ensure that the application that exposes the API to call is registered in API Gateway, Swagger 2.0 or OpenAPI 3 documentation is provided, and the endpoints are indexed.
  • Ensure that the API response Content-Encoding is set to identity with no compression or uses deflate compression.

  • Ensure that you specified the description property of the service account. The service accounts for the server application that exposes the APIs to call are created in the Infor OS Portal User Management user interface. This is required by ION.

    You can use the same service account in several API Gateway connection points. The credentials of this service account are used in these situations:

    • When calling the API from ION to perform a Test API Call.
    • When loading API Swagger or OpenAPI documentation.
    • At runtime, when ION performs the API Gateway step.

The definitions of an API Gateway connection point include:

  • The standard properties for any connection point, such as name, description, and tenant. For API Gateway connection points, the logical ID type is fixed to api. The logical ID is lid://infor.api followed by the converted name.
  • Authentication for connection to the target API.
  • Selection of API operation.
  • The documents that are sent and received and how the data is mapped to and from the API.
Note: To prevent possible issues, define one API per API Gateway connection point. If the connection point contains multiple APIs, errors in one API can affect the processing of other APIs.

Binary content

If you send binary content, such as images, archive files, or PDF documents, through API Gateway, ensure that the request option supports binary content. ION does not recognize and validate all cases during modeling. Requests with binary content can fail at runtime or succeed with corrupted data.

Binary content should be sent by using:

  • application/octet-stream request format
  • multipart/form-data request format
  • Any other request content type when an ANY document is used as input

Binary content cannot be sent by using:

  • Request parameters on the Request Parameters tab
  • application/x-www-form-urlencoded request format

Understanding binary data encoding in ION

When a file connection reads a binary file, such as an image, into a BOD document, for example, Sync.MyFile, the binary content is automatically base64-encoded. BOD documents are XML-based and support only text content. XML and JSON formats do not natively support raw binary data.

When a BOD is used as the input document for a multipart/form-data API call, the form-data parameter value contains a base64-encoded string instead of the original binary bytes.

If the target API expects raw binary content, such as image/png, the request fails because the target cannot interpret the base64-encoded string as a valid image or file.

Choosing the correct input document type for binary uploads

When you send binary content, such as images, PDF files, or archive files, through multipart/form-data, the input document type determines whether the data is transmitted in the original binary format or as a base64-encoded string.

  • Use an ANY document. This option is recommended.

    An ANY document preserves the native binary format of the file. When an ANY document is used as input and mapped to a form-data parameter through the Input Document column, the raw binary bytes are sent directly in the multipart request. Use this approach when the target API expects binary content.

  • Use a BOD document only when the target accepts base64-encoded strings.

    If the data flow requires a BOD as input, for example, Sync.MyFile, the file content stored in the BOD is base64-encoded. If the target API expects raw binary content, switch to an ANY document or modify the API contract to accept base64-encoded string content instead of binary content.

Note: Using a BOD such as Sync.MyFile to upload an image through multipart/form-data causes an error if the target API expects raw binary data.

Typical error messages include:

  • Unrecognized image format; accepted formats: GIF, JPG, PNG
  • Please set an image parameter with image data for value

These errors occur because the target receives a base64-encoded text string instead of the raw binary image data. To resolve these errors, use an ANY document as input, or modify the API Swagger definition to accept string content instead of binary content for the file parameter.