Remote Call-in

Procedure	Fit	Description
SOAP API	Good	Accessibility. FintechOS provides a SOAP API that remote systems can use to: publish events to notify your FintechOS organization query data create, update, and delete data obtain metadata about your organization run utilities to perform administrative tasks Synchronous API. After the API call is made, the remote client application waits until it receives a response from the service. Asynchronous calls to FintechOS aren’t supported. Generated WSDL. FintechOS provides two WSDLs for remote systems: Enterprise WSDL: Provides a strongly-typed WSDL that’s specific to a FintechOS organization. Partner WSDL: Contains a loosely typed WSDL that’s not specific to a FintechOS organization. Security. When executing SOAP API, you must have a have a valid login and obtain a session to perform any API calls. The API respects object-level and field-level security configured in FintechOS based on the logged in user profile. Transaction/ Commit Behavior. API calls allow partial success if some records are marked with errors. This can be changed to a behavior where all the results are rolled back if any error occurs. It’s not possible to span a transaction across multiple API calls. However, it is possible for a single API call to affect multiple objects.
REST API	Best	Accessibility. FintechOS provides a REST API that remote systems can use to: publish events to notify your FintechOS organization query data create, update, and delete data obtain metadata about your organization run utilities to perform administrative tasks Synchronous API. After the API call is made, the remote client application waits until it receives a response from the service. Asynchronous calls to FintechOS aren’t supported. REST API vs. SOAP API. REST API exposes resources (entities/objects) as URIs and uses HTTP verbs to define CRUD operations on these resources. Unlike SOAP, REST API requires no predefined contract, utilizes XML and JSON for responses, and has loose typing. REST API is lightweight and provides a simple method for interacting with FintechOS. Its advantages include ease of integration and development, and it’s an excellent choice for use with mobile apps and web apps. Security. The client executing REST API must have a valid token to perform any API calls. The API respects object-level and field-level security configured in FintechOS based on the logged in user’s profile. Transaction/ Commit Behavior. Every record is treated as a separate transaction and committed separately. Failure of one record change doesn’t cause rollback of other record changes. Use the REST API composite resources to make a series of updates in one API call.

For this pattern, FintechOS uses the following calling mechanism:

SOAP API: The remote system must authenticate before accessing any SOAP service. FintechOS system uses OAuth 2.0. The client must set the authorization HTTP header with the appropriate value (an OAuth access token can be acquired via an authentication call).
The remote system provides the WSDL file so that destination API can be generated in the FintechOS platform. The remote system generates client stubs that are in turn used to invoke the standard SOAP API.
REST API: The remote system must authenticate before accessing any REST service. FintechOS system uses OAuth 2.0. The client must set the authorization HTTP header with the appropriate value (an OAuth access token can be acquired via an authentication call).
REST invocations or HTTP requests are generated by the remote system with the appropriate verbs. Then, the results returned in JSON and XML data formats are processed.

The below table highlights the FintechOS properties best suited for the request and reply pattern.

Property	Mandatory	Desirable	Not Required
Event handling		X
Protocol conversion		X
Translation and transformation		X
Queuing and buffering	X
Synchronous transport protocols	X
Asynchronous transport protocols			X
Mediation routing		X
Process choreography and service orchestration		X
Transactionality (encryption, signing, reliable delivery, transaction management)	X
Routing			X

Error Handling and Recovery

Method	Strategy Description
Error handling	For remote call-in methods using standard or custom APIs, subsequent errors like timeouts and the retries management are handled by the remote system. Middleware can also be used for error handling and recovery.
Error recovery	For quality-of-service requirement, you need to create a custom retry mechanism. Idempotency should be enured.

Idempotence, Security, and Data Volumes Considerations

Idempotence

To ensure data integrity, the remote procedure called must have idempotent capabilities. Idempotency allows you to execute the same call many times and receive the same result.

NOTE
If errors or timeouts occur, multiple calls should be managed by the remote system to avoid duplicate inserts and redundant updates.

Security

The following security considerations are specific to using SOAP and REST API calls in this pattern.

SOAP API

Secure Sockets Layer v3 (SSL) and the Transport Layer Security (TLS) protocols are supported by the FintechOS platform. Ciphers must have a key length of at least 128 bits.
To obtain an access token, the remote system requires valid credentials. If the remote system has a valid token, the API call can be made without an explicit login.
The remote system must log in using valid credentials to obtain an access token. If
When using SOAP APIs, cache and reuse the access token to maximize performance.

REST API

Establish an OAuth trust for authorization. You can make REST calls on specific resources using HTTP verbs.
When using REST APIs, cache and reuse the access token to maximize performance.

Data Volumes

There is no theoretical size limit for payloads. However, due to performance and physical network connection constraints they should not very large (<10 MB). If large attachments must be uploaded, consider multipart transfers.

Both SOAP and REST APIs use a synchronous communication type.

Scenario Example

The below diagram illustrates the sequence of events when implementing this pattern and working directly with FintechOS objects.

FintechOS APIS can be called by the remote system to query the database and execute single-object operations such as create, update, delete, and so on.
FintechOS REST API composite resources can be called by the remote system to perform a series of object operations.
Custom-built FintechOS APIs can be called by the remote system to support multi-object transactional operations and custom pre/post processing logic.

Use Case

An insurance company uses the FintecOS platform to create a front end and manage insurance policies. The FintechOS asset records representing policies are stored in the database. Upon receiving a claim (for example a traffic accident happened, and the car must be repaired), multiple apps/ processes (variables) interested in the event are notified, some emails are sent, and then a Claim record is created.

The below constraints apply.

The Insurance company can participate in a contract-first integration (OpenAPI specifications), where FintechOS provides the contract, and the company acts as a client (consumer) of the FintechOS service.
No coding is necessary in FintechOS.

On the the FintechOS platform side:

Generate the OpenAPI specification and provide it to the remote system.

On the remote system side:

Create a client stub from OpenAPI specification.
Authenticate to the FintechOS platform (via OAuth web server or bearer token flow) using the integration user’s credentials.
Call the FintechOS API to create the claim that eventually updates to the policy.

NOTE
If more complex scenarios are needed, the Service Pipes component can be used but this scenario involves coding.

This example demonstrates the following:

Implementation of a FintechOS synchronous API client (consumer).