1

2
3
Note: The OpenAPI specification was originally known as the Swagger specification.
This document uses both these terms interchangeably.

4
The IRIS design time flow for provider API development is,
1. Discover resources in the core banking (T24) system to expose as RESTful services.
Versions and enquiries are the main core banking(T24) resources for a business
functionality. Assign resource names for each resource.
2. Generate an inventory file in JSON format for intended T24 versions and enquiries
with selection criteria parameters
3. Pass inventory JSON as input to generate OpenAPI(Swagger) definition for the T24
resources
4. Pass inventory JSON and Swagger JSON as input to generate camel xml
5. Import generated artefacts in design studio service project and orchestrate the
service as needed
6. Build and package generated and/or modified artefacts and the dependencies
into a web application
7. Deploy to development container for consumption from a REST client

5
The objective of this Lab exercise is to identify the steps to
1. create a provider API and
2. query the service

6
Listed are the tools needed for developing a RESTful service for T24 resources using
IRIS R18.

7
Before starting the project creation ensure that archetype-catalog.xml file is made
available in the default internal catalog location which is the users .m2 directory or
any local path

This xml configuration file stores details of two archetypes - the service container and
service archetypes.

What is Archetype?
Archetype is a Maven project templating toolkit. It is a model from which projects
can be cloned. Archetypes provide a consistent means of generating Maven projects
for developers.

Knowledge about archetypes is stored in catalogs. If the xml is placed in a local path
instead of the default location, then browse and add the file manually as shown.

8
In order to run any API projects, you must have a service container. A service
container hosts one or more service projects.

You can create the service container using the supplied Maven Archetype, either from
your IDE.

• From the File menu, select File > New > Maven Project. Click Next.
• Add archtetypes catalog as a Local catalog as shown in the previous step. Select
the checkbox include snapshot archetypes if you are working with snapshot
release. Type a filter text ‘irf’.
• Select irf-service-container-archetype and click next
• Fill in the Group Id, Artifact Id and Version fields, and click Finish. Group
Id identifies the project uniquely across all projects. It has to follow the package
name rules. Artifact Id is the name of the jar without version created as the output
of a maven build. Version is a typical version for the jar.

Container project is created with a structure as shown.

9
The service container must know how to connect to T24. T24 connection properties
are set in a file standalone-comms.properties.

Set the correct jboss AS provider URL in the property java.naming.provider.url. Pass
valid T24 credential in the property t24.security.context. Set a desired connection
timeout

10
Build and install the service container. In Eclipse,
• Right click on the container project > Run As > Maven build.
• Supply a name for the configuration for identification
• Type the Goal as clean install
• Click on Run

The Maven Clean Plugin, attempts to clean the files and directories generated
by Maven during its build. The Clean Plugin assumes that these files are generated
inside the target directory. The Maven Install Plugin, frames a dependency tree based
on the project configuration pom.xml on all the sub projects under the super
pom.xml (the root POM) and downloads/compiles all the needed components in the
local repository.

11
Start jetty server to consume the deployed services. In Eclipse,
• Right click the container project > Run As > Maven Build (second item in list)...
• In the dialog box, set the goals to jetty:run
• Click on Run

Jetty runs at default port 8080. To change the port at runtime, use the property
jetty.http.port

mvn jetty:run -Djetty.http.port=9999

12
IRIS management service displays the deployed services in the service container and
their respective URLs.

Access the management service at the URL

/v1.0.0/meta/apis

In case of connection errors, verify the T24 connection properties in standalone-

comms.properties.

Identify the list of services deployed in the jetty container and their endpoints.

13
View the artefact availability status at the API status URL
/v1.0.0/meta/apis/status

14
Catalog services provide list of schemas hosted in the IRIS Container.

Use the catalog services URL - localhost:8080/api/v1.0.0/meta/apidocs for the list of

swagger schema URL of the services. Click on a URL to view the swagger schema
definition as shown.

15
16
The interaction framework workbench is a development toolkit that facilitates
generation of IRIS service artefacts effortlessly. The workbench has,
a) Dashboard - for management and reporting, and to list deployed services.
b) API menu - to create service artefacts for provider API and to import service
definition for publisher API.
c) Vocabulary entries – list of allowed identifiers to use while naming resources,
fields etc for standardization and consistency.
d) Settings menu to modify default API configuration and jetty server

Launch the workbench using the url http://localhost:<jboss port>/irf-web-client. Set

the default service configuration using the Settings menu.

17
Click on create provider api from the API menu

In the Service Definition section, click on Choose File to navigate to a pre-existing

inventory json. Information from the inventory json is populated in the workbench

18
Click on Next and Finish.

This will generate IRIS resources – inventory json, swagger json, camel xml, mock
responses and test routines. Click on the Download button to download the
generated service artefacts. Extract the zip to view the contents

19
20
To develop a provider service API, you need a service project.

Create a service maven project using the irf-service-archetype.

• Select the irf-service-archetype and click next
• Fill in the Group Id, Artifact Id and Version fields, and click Finish.
A project is created with the structure in the snapshot.

The provider service project cloned from irf-service-archetype, comes pre-loaded

with a sample inventory and swagger JSON. Delete the existing files from
src/main/resources folder. Extract the contents of the downloaded artefacts from the
workbench into the src/main/resources folder.

21
• The inventory is a file that defines Core banking (T24) resources that the API
invokes. The main resources are versions and enquiries.
• The inventory json generated, defines the API version
FUNDS.TRANSFER,FT.API.INITIATE.PAYMENT.1.0.0 to initiate a payment on an
account and enquiry FT.API.PAYMENT.STATUSREPORT.1.0.0 to list all payment
transactions on an account.
• A unique URL path is given to each resource along with a HTTP method (POST, PUT,
GET, DELETE) to perform a specific CRUD operation on the resource.
• resourceType identifies whether the API is exposing an Enquiry (Query) or Version
(Screen)
• Query parameters in a request URL are mapped to selection fields of a T24
enquiry. This information is available in the selections block
• The value in Descript field in Enquiry and Description in Version becomes
operationId. operationId uniquely identifies a service in IRIS

22
The inventory file is used to create the Swagger specification of the API. The
generated swagger definition, describes and documents your RESTful API. The API is
described using JSON. It contains,
a) general information about the API
• Swagger version used by the API i.e., 2.0.
• API info like the ‘version of the API’ i.e., 1.0.0 and title is provided under the info
block.
b) an inventory of the available resources. The paths section defines,
• Individual endpoints (paths) in the API, and the HTTP methods (operations)
supported by these endpoints.
E.g., GET /order/payment/{accountId}/status
• Operations that have parameters that can be passed via URL path -
(/order/payment/{accountId}/status), query string -
(/order/payment/{accountId}/status?startDate=2017-01-01&viewType=PENDING)
and request body
• The parameter types, format(date, amount), whether they are required or
optional, and other details
• The MIME type supported by the API i.e., application/json in the produces field

23
The snapshot shows the resource definition of the T24 version
FUNDS.TRANSFER,FT.API.INITIATE.PAYMENT.1.0.0 exposed in the API.

For each operation, schema of the request and response header and body is defined.

Note: The swagger definition document of your API is intended to be exposed to the
external world. It is recommended that necessary and relevant information is added
to the document. Install swagger editor which is an open source editor to design,
define and document your RESTful APIs in the Swagger Specification.

24
The inventory file and the generated Swagger definition are used to create the service
implementation. The generated Camel XMLs defines the REST endpoints and the
camel routes. The endpoints are exposed in <rest> tag. As expected there are two
endpoints, one each for the version and enquiry. The camel XMLs in the snapshot
defines a REST service with the following URL mappings
Base path = /v1.0.0/order/payment
URI template = /{accountId}/status, HTTP Verb = GET
URI template = /initiate, HTTP Verb = POST
Camel routes which wire the endpoint to the backend are defined in the <route> tag.
There are 3 routes –
1) direct-vm:order-payment.getPaymentStatusReport – to the enquiry
FT.API.PAYMENT.STATUSREPORT.1.0.0
2) direct-vm:order-payment.createPaymentTransfer – to the version
FUNDS.TRANSFER,FT.API.INITIATE.PAYMENT.1.0.0 and
3) direct:mockResponder – to the mock responder
At runtime, the REST endpoint receives request in JSON format. Camel router, routes
the message to T24 version or enquiry processor, which transforms the JSON
message to OFS.

25
The tooling also generates responder JSON files to return a mocked response.

26
27
Build the service project into an ‘artifact’ (*.jar) to install it in the local maven
repository. The console output of mvn clean install is shown. The service project can
then be added as a dependency to the service container project.

28
Add a new dependency in the pom.xml of the service container.
• Copy groupId, artifactId and version information from pom.xml of the service
project.
• Paste this information within <dependency></dependency> tag in <dependencies>
section
This adds the newly created service as a dependency in the container project.
• Restart jetty server.
• Access the service management URL at /v1.0.0/meta/apis and verify that the
newly added service is displayed along with its endpoints.

29
The service catalog URL is at :
GET: http://localhost:8080/api/v1.0.0/meta/apidocs

Click on the OAS definition URL of a service to view the swagger document.

30
Test the API using a REST client like postman.

Send a query request as shown

GET /v1.0.0/order/payment/{accountId}/status

E.g., GET - http://localhost:8080/api/v1.0.0/order/payment/21067/status

The response payload displays the transactions done on the accountId passed in the
query path in JSON format.

31
Send a transaction request using the screen endpoint.
POST /v1.0.0/payments/transfer/initiation
E.g., - POST - http://localhost:8080/api/v1.0.0/order/payment/initiate

• Select the method as POST

• Type the service URI for the version
• Click on Body and select raw
• In the editor paste the request payload as shown
• Click on Headers and add the header “Content-Type” with a value
“application/json” and click on send

The response is displayed with a status 200 OK. Verify the transaction in T24 browser.

32
33
This exercise helps you to
• Identify steps to use workbench for creating the service resources – inventory,
swagger definition, camel xml routes, mock responses and test routines.
• Import the service definition into service project in EDS.
• Build and install service project and make it available for consumption from a REST
client

34
Ensure jetty server is running at port 8080. Verify by accessing the management URL
at : http://localhost:8080/api/v1.0.0/meta/apis

35
Click on create provider api from the API menu

In the Service Definition section, provide the Artifact Id in Key, the service title and
description. Version, Base Path and Host defaults from the settings done earlier.

The workbench browses T24 for versions, enquiries and product groups that are
intended to be exposed through the API and lists them in the Available Artefacts
section. The rules for creating API versions and enquiries in T24 are discussed in
another session.

From the available artefacts section, add SMALL.BUSINESS.GROUP product group by

clicking on the + button. From the expanded section on the right, select the following
Product – Small Business Loan.
Activity – New arrangement
Supply,
• an allowed Operation verb like create, update etc.,
• a domain for grouping the service from the drop down list,
• URL method as POST to create a new arrangement and
• a valid URL using standard REST API naming conventions available in vocabulary.

36
Add required property for the Request and response payload

37
Click on Next.

The inventory file is automatically generated for the activity LENDING-NEW-

ARRANGEMENT for the product SMALL.BUSINESS.LOAN using the information
supplied in the previous form and introspection from T24.

Click on Finish.

This will generate swagger json, camel xml and other service resources. Click on the
Download button to download generated service artefacts. Extract the zip to view its
contents

38
39
40
The artefacts downloaded from the workbench has to be imported into a service
project in design studio.
In design studio, create a new Provider API service project e.g., provider-AALoans.
• Supply a Group Id and Artifact Id. It is recommended to match the names given in
the workbench.
• Extract the contents of the downloaded artefacts from the workbench into the
src/main/resources folder.

41
42
POST an arrangement from REST client using the endpoint URL defined for the service
POST - localhost:8080/api/v1.0.0/holdings/smallBusinessLoans

View the response body.

43
Note: set FIELD.VAL = YES in GCS record of OFS.SOURCE,

44
The objective of this lab exercise is to identify the usage of swagger UI tool in the
workbench to test service endpoints

45
The Swagger UI tool is incorporated in the workbench. It takes OpenAPI specification
files of the RESTful service as input, presents the service visually and allows you to
execute operations.

To launch Swagger UI in the workbench, click on Dashboard > Deployed Services.

Click on Api docs for the service. Alternatively, launch Swagger UI tool using the URL
localhost/public/dist. This takes the apidocs URL as a parameter. [Access the Service
Catalog. Copy OAS URL for the FT service. Append the copied schema URL as a query
parameter to localhost/public/dist?url=<schema URL>]

46
Test FT payment status report API by clicking on the GET link > Try it out. The tool
loads a UI with text boxes for the input parameters.
• id is part of the URL string and is a mandatory parameter
• startDate, endDate etc can be passed as query parameters.
The request is executed in T24 and a JSON response is displayed with a status code
200.

47
Initiate a payment transfer on an account by clicking on the POST link. The payload is
populated with the request body schema. Supply required data to the fields. The
request is executed in T24 and the response body is displayed.

48
49
Request parameters are sent along with the request typically as part of the URL i.e.,
in the query string. They can also be sent as part of the body of the HTTP request.
The standard request parameters to use with IRIS API are listed in the table.

50
Pagination is controlled via two parameters, page_size and page_start. The
maximum number of resources the server returns in the response to a list request is
controlled using the page_size parameter.

51
Caching is controlled via the parameter page_token. There is no T24_time element to
the audit, as the request has been served from cache.

52
53
54