API Development
An API defined in Swagger 2.0 is imported into an API project. Import process will create the Camel routes, mock responses and wire the routes to the mock
responses. This is done using a Maven plugin, either from your IDE or from the command line.
Getting Started
The table below describes the technical terminologies used in the solution.
Terms Description
Swagger Swagger is an open source software framework backed by a large ecosystem of
tools that helps developers design, build, document, and consume RESTful Web
services.
Apache Camel Apache Camel is an open source framework for message-oriented middleware
with a rule-based routing and mediation engine that provides a Java object-
based implementation of the Enterprise Integration Patterns using an
application programming interface (or declarative Java domain-specific
language) to configure routing and mediation rules.
Archetype It is defined as an original pattern or model from which all other things of the
same kind are made.
Maven Maven is a build automation tool used primarily for Java projects.
Inventory It is a file that provides the information of an API in core banking terms. It helps
in creating the service implementation by generating swagger specification of
an API.
payload The actual information or message in transmitted data, as opposed to
automatically generated metadata.
Deployment A deployment descriptor refers to a configuration file for an artifact that is
Descriptor deployed to some container.
The following steps are required for API development:
Creation of Artefacts in T24- This section explains how data is retrieved from T24 system and provided to IRIS to expose to external requests. This in turn
reduces the data loads being retrieved and simplifies the whole process. Also, it can be referred as filtering of T24 data by T24 being expose to the
external request.
Creation of Service Project- It contains the default directories and set of model data. It basically acts as a platform where developers can build and run
the required APIs. It also contains a set of archetypes which gives developers options of creating desired APIs.
Creation of Provider API- Provider APIs expose core banking capabilities as RESTful APIs. The key concept is that each Provider API is driven from an
inventory that defines the contents of the API in core banking terms. The inventory is used to create the Swagger specification of the API. Together, the
inventory file and the generated swagger specification are used to create the service implementation.
Creation of Published API- Publisher APIs provide the following REST resources:
Login
Logout
Add API, Update API, Remove API, Copy an API
Validation roles
Note: When you access any API other than the login and logout APIs through an external REST client, first invoke the login API to ensure that user is
authenticated. When the login API is invoked, the system stores the generated session cookie in a file, which we use in the next API invocations.
Workbench Installation
Workbench binaries are available as irf-web-client-release.zip bundle T24 Binaries available in the T24 Installation.
1. Copy the content “web-client folder” available in T24 Binaries under com\temenos\irf\irf-test-webclient\xxxx.x.x .
xxxx.x.x – latest artefact version of workbench available
2. Extract the content of “web client” folder bundle into <Apache HTTP Server Installation Home >\htdocs folder.
Creation of Artefacts in T24
Artefacts need to be created to expose the core banking features to external parties. In IRIS R18, T24 Versions and Enquiries are used as base artefacts to expose
the core banking features through API development.
Note: If you have existing artefacts, then you can skip this step and navigate to Create Service Project step.
In order for T24 Version and Enquiry artefacts to be used in the Interaction Framework, certain rules must be followed. These rules provide a simple and effective
governance framework that
Clearly identifies that a given T24 artefact is used in an API
Allows simple versioning control to be applied to the T24 artefact following semantic versioning (refer http://semver.org/)
Provides data type meta data to ensure clean conversion of data from T24 to internet standard data types
Provides meaningful operation names
The following rules must be followed:
ID Naming Convention
For Enquiry, the following ID naming convention must be followed:
Examples: PZ.API.ACCOUNTS.BALANCES.1.0.0, PZ.API.ACCOUNTS.TRANSACTIONS.1.0.0
For Version the following ID naming convention must be followed:
Example: FUNDS.TRANSFER, AC.API.CREATE.TRANSFER.1.0.0
Field data typing
Each Enquiry column and Version field must have a data type defined. For Enquiry, this is the FIELD.DISP.TYPE field, for Version the TOOL.TIP field is used. Fields are
considered to be alphanumeric unless they are set as Date or Amount. Amount and date fields must be unformatted, e.g. 20170123 and 1234.56
Description
Each Enquiry and Version must have a description. For Enquiry, this is the DESCRIPT field, for Version the DESCRIPTION field is used.
Restrictions on Enquiry
Header fields should not be used in API enquiries.
Naming should be in standard vocabulary
The standard Temenos vocabulary exists to bring consistent naming across all API initiatives. Field / main resource / sub resource names should exist in the
standard vocabulary.
Click here to know how the T24 enquiry definition affects the JSON response.
Note: If there is an existing Service Project, you can skip Create Service Project step and navigate to Provider API step.
Creation of Service Project
Create a service project using the irf-service-archetype.
Using the command line
mvn archetype:generate -DarchetypeGroupId=com.temenos.irf -DarchetypeArtifactId=irf-service-archetype
-DarchetypeVersion=1.0 -DarchetypeCatalog=local
Supply values for various arguments, either interactively or as parameters from the command line:
Define value for property 'groupId': com.temenos.training.irf
Define value for property 'artifactId': training-api
Define value for property 'version' 1.0-SNAPSHOT: :
Define value for property 'package' com.temenos.training.irf::
Confirm properties configuration:
groupId: com.temenos.training.irf
artifactId: training-api
version: 1.0-SNAPSHOT
package: com.temenos.training.irf
As a single command:
mvn archetype:generate -DarchetypeGroupId=com.temenos.irf -DarchetypeArtifactId=irf-service-archetype
-DarchetypeVersion=1.0 -DartifactId=training-api
-DgroupId=com.temenos.irf.training -Dpackage=com.temenos.irf.training -Dversion=SNAPSHOT-0.0.1
Using Eclipse
From the File menu, select File > New > Maven Project
Click the Next button.
Select archetype
Select the irf-service-archetype option from Artifact Id column and click the Next button.
Provide Project details
Fill in the Group Id, Artifact Id and Version fields, and click the Finish button.
Project Structure
You should see a project created with the following structure:
Using Workbench to Define Provider API
The easiest mechanism to create a Provider API is to use the Interaction Framework Workbench. Select "APIs > Create Provider API":
Step 1 - Start Service Container
Make sure that, Service Container is up and running.
http://localhost:8080/api/v1.0.0/meta/apis
If it is not running, start the server using the following command
jetty:run from maven command prompt
Step 2 - Service Definition
Provide the Title, service Key, Description , etc in the Service Definition section
Step 3 - Select Artefacts to include
Artefacts may be filtered to aid in discovery. Clicking on an artefact will add an endpoint to the service, and create a URL based on the artefact definitions. Review
the URL and Operation to ensure that this matches the API design. An end point may be removed by clicking on the trash icon in the top right of the endpoint
definition.
Step 4 - Map URL parameters to Query Selection
Where a T24 VERSION is selected, only the method is required to be set. The payload will be configured in Swagger directly from the T24 Model. POST should be
used to create new resources, PUT to amend and existing resource, GET for viewing a resources and DELETE for removing a resource.
Where a T24 ENQUIRY is selected, the URL parameters need to be mapped to the ENQUIRY selection fields.
A selection field can be mapped from mulitple URL query or path parameters. In the above example, fromDate and toDate are both mapped to the valueDate
selection field.
Click Next in the top right fo the screen to review the provider API
Step 5 - Review
The inventory file can be copied directly from the Inventory pane and pasted into an IDE. Or if preferred click Finish to create a zip file file containing the swager
spec, Camel routes, mappings and mock responses.
Step 6 (optional) - Submit
Click Finish the top right fo the screen to submit the provider API
The result provides a link to download a zip file containing the swager spec, Camel routes, mappings and mock responses.
Step 7 Importing generated Artifacts
Extract the content of downloaded zip into <service-provider> project/ resources folder.
Project Structure
Step 8 - Build The Provider API Project
Run the project as Maven > Install to build the project
Build the Service Project
Right click the project and choose Run As > Maven install to build the project.
Creation of Service Container
In order to run any API projects, you should have a service container. A service container hosts one or more service projects. It is also a runtime container that
hosts the camel run time and configuration required to connect to downstream systems, i.e. T24
You can create the service container using the supplied Maven Archetype, either from your IDE or from the command line.
Using the command line
mvn archetype:generate -DarchetypeGroupId=com.temenos.irf -DarchetypeArtifactId=irf-service-container-archetype
-DarchetypeVersion=1.0
Supply values for various arguments, either interactively or as parameters from the command line:
Define value for property 'groupId': com.temenos.training.irf
Define value for property 'artifactId': training-container
Define value for property 'version' 1.0-SNAPSHOT: :
Define value for property 'package' com.temenos.training.irf::
Confirm properties configuration:
groupId: com.temenos.training.irf
artifactId: training-container
version: 1.0.0-SNAPSHOT
package: com.temenos.training.irf
As a single command:
mvn archetype:generate -DarchetypeGroupId=com.temenos.irf -DarchetypeArtifactId=irf-service-container-archetype
-DarchetypeVersion=1.0 -DartifactId=training-container
-DgroupId=com.temenos.irf.training -Dpackage=com.temenos.irf.training -Dversion=SNAPSHOT-0.0.1
Using Eclipse
From the File menu, select File > New > Maven Project
Click the Next button.
Select Archetype
Select the irf-service-container-archetype option from Artifact Id and click the Next button.
Provide Project Details
Fill in the Group Id, Artifact Id and Version fields, and click the Finish button.
Project Structure
You should see a project created with the following structure:
Start the server
You can now start the server, either from the command line or from your IDE using mvn jetty:run
mvn jetty:run
In Eclipse, right click the project and select Run As > Maven Build
In the dialog box, set the Goals to jetty:run
Creation of Provider API
Provider APIs expose core-banking capabilities as RESTful APIs. The key concept is that each Provider API is driven from an inventory that defines the contents of
the API in core banking terms. The inventory is used to create the Swagger specification of the API. Together, the inventory file and the generated swagger
specification are used to create the service implementation.
Creating an Inventory using Interaction Framework Workbench
The easiest mechanism to create a Provider API is to use the Interaction Framework Workbench. Select "Create Provider API":
Step 1 - Service Definition
Provide the Group and Key (used in as the Group in the Maven artefact), the service title and the version of the service.
Step 2 - Select Artefacts to include
Artefacts may be filtered to aid in discovery. Clicking on an artefact will add an endpoint to the service, and create a URL based on the artefact definitions. Review
the URL and Operation to ensure that this matches the API design. An end point may be removed by clicking on the trash icon in the top right of the endpoint
definition.
Step 3 - Map URL parameters to Query Selection
Where a T24 VERSION is selected, only the method is required to be set. The payload will be configured in Swagger directly from the T24 Model. POST should be
used to create new resources, PUT to amend an existing resource, GET for viewing a resource and DELETE for removing a resource.
Where a T24 ENQUIRY is selected, the URL parameters need to be mapped to the ENQUIRY selection fields.
A selection field can be mapped from mulitple URL query or path parameters. In the above example, fromDate and toDate are both mapped to the valueDate
selection field.
Click Next in the top right of the screen to review the Provider API.
Step 4 – Review
Note: The inventory file can be copied directly from the Inventory pane and pasted into an IDE or if preferred click Finish to create a zip file containing
the swagger spec, Camel routes, mappings and mock responses.
Click here to know how to create a zip file containing the swagger spec, Camel routes, mappings and mock responses.
Create Service Project
Create a service project using the irf-service-archetype.
Using the command line
mvn archetype:generate -DarchetypeGroupId=com.temenos.irf -DarchetypeArtifactId=irf-service-archetype
-DarchetypeVersion=1.0 -DarchetypeCatalog=local
Supply values for various arguments, either interactively or as parameters from the command line:
Define value for property 'groupId': com.temenos.training.irf
Define value for property 'artifactId': training-api
Define value for property 'version' 1.0-SNAPSHOT: :
Define value for property 'package' com.temenos.training.irf::
Confirm properties configuration:
groupId: com.temenos.training.irf
artifactId: training-api
version: 1.0-SNAPSHOT
package: com.temenos.training.irf
As a single command:
mvn archetype:generate -DarchetypeGroupId=com.temenos.irf -DarchetypeArtifactId=irf-service-archetype
-DarchetypeVersion=1.0 -DartifactId=training-api
-DgroupId=com.temenos.irf.training -Dpackage=com.temenos.irf.training -Dversion=SNAPSHOT-0.0.1
Using Eclipse
From the File menu, select File > New > Maven Project
Click the Next button.
Select archetype
Select the irf-service-archetype option from Artifact Id column and click the Next button.
Provide Project details
Fill in the Group Id, Artifact Id and Version fields, and click the Finish button.
Project Structure
You should see a project created with the following structure:
Submit the Provider API
After creation of inventory file as shown in Step 4 of the Creating an Inventory using Interaction Framework Workbench.
Click Finish in the top right of the screen to submit the provider API.
The result provides a link to download a zip file containing the swagger spec, Camel routes, mappings and mock responses.
Build the Service Project
Run the project as Maven > Install to build the project
Click here to know about T24 Connectivity Configuration TAFJ and TAFC
Deploy and Test Provider API
Add to the Service Container Project
In your service container project, amend the pom.xml to include your API as a dependency:
NB There are several dependencies tags in the pom.xml file - this dependency needs to be added to the MAIN dependency, below the comment:
<!-- Add any project dependencies here-->
<dependency>
<groupId>com.temenos.training</groupId>
<artifactId>provider-accounts</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
The service container should restart automatically, if not stop the server and restart manually.
Check Deployment
Use Postman to make a GET request to the management service
localhost:8080/api/v1.0.0/meta/apis
You should see the servicer returned in the response:
"header": {
"serviceCount": 9,
"audit": {
"processTime": 9
}
},
"body": [
{
"service": "provider-accounts.service.v1.0.0",
"endPoints": [
{
"method": "POST",
"uri": "/v1.0.0/provider-accounts/payments"
},
{
"method": "GET",
"uri": "/v1.0.0/provider-accounts/{accountId}/transactions"
}
]
},
{
"service": "accounts.service.v1.0.0",
"endPoints": [
{
"method": "GET",
"uri": "/v1.0.0/accounts/{AccountId}/transactions"
}
]
},
Exposing AA Activities as Provider APIs
Service configuration
Define the Service Definition parameters for "New Arrangement creation" for a commercial loan product.
Select the "LENDING" under the "Available artifact" section and add it
Enter Arrangement Activity & Product Details
Select the
Activity : New Arrangement
Product Group: Small Business Loan
Product: Small Business Loan
Download the Generated Artifacts
Click Next and click Finish.
Workbench will display a URL link to download the generated artifacts.
Create Lending API project using eclipse Maven Arche Type
1. Create provider api project for Lending Product using the Maven Arch type.
a. Select "irfarchetype" of Dev.0.0.0-Snapshot Version
b. Enter Service API project details
Group Id : com.temenos.irf.training.aalending
Artifact id : provider-smallbusinessloan-service
Click Finish.
Import and Build the Generated Artifacts
1. Extract the generated artifacts into the resources/services folder of the Lending API project created from the Service API maven archetype.
2. Build the Service API project using maven command
mvn clean install
3. Add dependencies of API maven project in the Container maven pom.xml under "dependencies" section.
<dependency>
<groupId>com.temenos.irf.training.aalending</groupId>
<artifactId>provider-smallbusinessloan-service</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
4. Build and Restart the Container project
Test Small Business Loan Service
1. Test the Service from Postman using the below Url
a. URL :http://localhost:8080/api/v1.0.0/lending/small.business.loans/small.business.loan
b. data :
{
"header": {
},
"body": {
"customerId": "100100",
"currency": "USD",
"commitment" : {
"amount": "7000",
"term": "1Y"
}
}
}
2. and Post the request
3. Get success response with the Arrangement details
Creation of Published API
Overview
An API defined in Swagger 2.0 may be imported into an API project. The import process will create the Camel routes, mock responses and wire the routes to the
mock responses. This is done using a Maven plugin, either from your IDE or from the command line.
Creation of Provider Service Project
From the File menu, select File > New > Maven Project
Click Next
Select archetype
Select the irf-service-archetype and click next
Provide project details
Fill in the Group Id, Artifact Id and Version fields, and click Finish.
Project Structure
You should see a project created with the following structure:
Import API Spec
The import process is done using the Interaction Framework Workbench. Go to APIs > Import API Definition. You should be able to see the following screen.
Select the publisher swagger definition (swagger json file) that you want to import and then click Upload
Give your service a name in the next screen and click Upload & Generate
Download and extract the zip and place the generated files in the service project
Project Structure
Refresh the project view and verify the project structure:
Provider API to Published API Mapping
Map path params from publisher to provider
Route for published Funds Transfer Status Report
...
<rest path="/v1.0.0/published" produces="application/json" id="published.service.restlet">
<get uri="/payments/{accountid}/statusreport" id="PublishedPaymentStatusReport">
<param name="accountid" type="path" required="true"/>
<to uri="direct:published.PublishedPaymentStatusReport"/>
</get>
</rest>
...
<route id="direct.published.PublishedPaymentStatusReport">
<from uri="direct:published.PublishedPaymentStatusReport"/>
<to uri="direct-vm:order-PSD2.getPaymentTransferList" />
<process ref="FTStatusReportResponseMapper"/>
</route>
Note: Use "direct-vm" component to map all the publisher path params to provider path params. This will enable it to look through all the
CamelContexts present in the same JVM and route to the underlying provider API.
Save all the files, and build the publisher api project as Maven > Install.
Sample Publisher route for the reference
Additional Beans before CamelContext tag
...
<bean id="FTInitiationRequestMapper"
class="com.temenos.irf.published_FT_api.FTInitiationRequestProcessor"/>
<bean id="FTInitiationResponseMapper"
class="com.temenos.irf.published_FT_api.FTInitiationResponseProcessor"/>
<bean id="FTStatusReportResponseMapper"
class="com.temenos.irf.published_FT_api.FTStatusReportResponseProcessor"/>
<bean id="FTSubmissionResponseMapper"
class="com.temenos.irf.published_FT_api.FTSubmissionResponseProcessor"/>
...
Published FT Status Report Route
...
<get uri="/payments/{accountid}/statusreport" id="PublishedPaymentStatusReport">
<param name="accountid" type="path" required="true"/>
<to uri="direct:published.PublishedPaymentStatusReport"/>
</get>
...
<route id="direct.published.PublishedPaymentStatusReport">
<from uri="direct:published.PublishedPaymentStatusReport"/>
<to uri="direct-vm:order-PSD2.getPaymentTransferList" />
<process ref="FTStatusReportResponseMapper"/>
</route>
Published FT Initiation Route
...
<post uri="/payments/transfer/initiation" id="PublishedPaymentTransferInitiation">
<to uri="direct:published.PublishedPaymentTransferInitiation"/>
</post>
...
<route id="direct.published.PublishedPaymentTransferInitiation">
<from uri="direct:published.PublishedPaymentTransferInitiation"/>
<process ref="FTInitiationRequestMapper"/>
<to uri="direct-vm:order-PSD2.getPaymentTransferList" />
<process ref="FTInitiationResponseMapper"/>
</route>
Published FT Submission Route
...
<post uri="/payments/transfer/{id}/submission" id="PublishedPaymentTransferSubmission">
<param name="id" type="path" required="true"/>
<to uri="direct:published.PublishedPaymentTransferSubmission"/>
</post>
...
<route id="direct.published.PublishedPaymentTransferSubmission">
<from uri="direct:published.PublishedPaymentTransferSubmission"/>
<to uri="direct-vm:order-PSD2.getPaymentTransferList" />
<process ref="FTSubmissionResponseMapper"/>
</route>
The request and response mappers configured will have java code to transform from publisher json format to provider json and vice versa.
Published on: 22/05/2019
