Aperio Backend

To allow programmers to write RPG programs which will act as API we had to create Aperio Backend layer. This is a simple new library (IAF100AP) which should be included in RPG projects. This new library plays two roles in the API landscape:

1. Delivers RPG tools for RPG developers needed to easly write RPG programs which will act as APIs.
2. It contains communication mechanisms which allows RPG programs to communicate with API Bridge in standardized way.

The typical installation of Aperio Backend (IAF100AP) is to just put it on IBM i and set up the system so that this new library is available during compilation and runtime of RPG programs . Library IAF100AP must be on the library list.

IADF - Iptor API Data Format

To standardize communication between API Bridge and IBM i we established IADF (Iptor API Data format). We agreed that RPG programs will communicate with API Bridge in a special way. It will exchange JSON strings. Incoming JSON string has the following structure:

{
    "control":{...},
    "params:"{...}
}

It contains two sections (objects):

• control - which is used to pass control information like which program to call or should it open files prior to call, to how many records limit response, etc….
• params - entry parameters for RPG program.

example:

{
    "control":{
        "program": "MGRR001",
        "openCrossRef": true,
        "limit": 15
    },
    "params": {
        "warehouse": "BRI",
        "item": "TEST-ITEM01"
    }
}

The example above showss how the incoming json may look like if you want to run MGRR001 RPG program with parameters Warehouse=BRI and item=TEST-ITEM01. It also tells that response should be limited to 15 rows only, and Aperio should open cross reference files before calling MGRR001.

The response from RPG program is also standardized and transferred to API Bridge as json:

{
    "control":{...},
    "data":{...},
    "messages":[...],
    "error":{...}    
}

It contains up to 4 sections (objects).

• control - conveys some technical information about RPG program call. Like total number of rows in file etc… This section may appear in response or not
• data - this is main object which contains response data from RPG program. This element may appear or not.
• messages - here you can find messages which were issued (if any) by RPG program. This element may appear or not.
• error - in case of error this object is also sent in response. It contains code of error with short description. This element may appear or not.

To help programmer to write RPG program and to keep standard communication with API Bridge, a set of procedures were prepared in Aperio backend. Here You can find the reference list of these procedures.

Installation

The instalation routine you can find here.

Configuration

The configuration can be divided into 3 sections:

• Aperio Backend related libraries
• Aperio Backend framework configuration
• How to configure API Bridge to be inline with Aperio Backend

Aperio Backend related libraries

Mainly Aperio Backend is delivered as one library (IAF100AP). The easiest way to configure Aperio is to just restore this library and place in the library list. In DC1 we achieve it by using Additional products. Aperio Backend library contains set or programs/service-programs which are used do develop RPG API. Additionally, Aperio Backend keeps information about RPG API programs. This information is kept in files. If your environment is simple, you don’t need to do more about it. But in case you have on the same machine (IBM i) a Production company, a Test company and Development company then you probably need to differentiate information about API. Some API are available on development and some only on production. More complex situation is when in the same IBM i you have many customers (multitenant instalation). Then definitely there is a need to differentiate Aperio data. In this case, when Aperio Backend is initialized you can decide to initialize extra library for Aperio Backend Data. For example: CUSTADTA. Then this library must be placed above IAF100AP on the library list.

Library list on IBM i for customer A

    ...
    CUSTADATA
    IAF100AP

Library list on IBM i for customer B

    ...
    CUSTBDATA
    IAF100AP

Libraries CUSTADATA and CUSTBDATA will contain (metadata, control, config and notification) data, where IAF100AP will contain Aperio Backend programs. If you log in to customer environment company you should see correct library list. Additionaly if you see screen for command WRKAPIMTH then press F8 - you should see that the framework is located in IAF100AP and the data is located in sepearte library.

Aperio Backend framework configuration

In prevous chapter it was described that Aperio data can be kept in a separate library. Depending if you want to differentiate configuration per companies/customers or you want to keep it simple the same for all tenants, you can choose model with one or many libraries. To see which library is used to store the config information, type WRKAPIMTH on IBM i command line (5250) adn then press F8. See where the config is located. To maintain config type use command WRKAPIMTH and press F7. There are two sections:

• Exit points (predefined configuration comes with Aperio. change it only if really needed)
• External API servers (this configuration is barelly used by customers).

The detailed information about Aperio backend config you can find here. The detail information about exit point you can find here.

How to configure API Bridge to be inline with Aperio Backend

This chapter describes how to configure API Bridge to reflect library list on IBM i. The “environment” section of the configuration of API Bridge sets the initial library list. In simple installation at the end of the initial library list there is IAF100AP (see bellow).

Simple example of API Bridge configuration

{
        "environment": {
                "libraryList":"A120ENV,DEV121AS,DEV121AP,A120AP,IAF100AP",
                "serviceProgram": "IAFS0001",
                "initMethod": "environment.init",
                "parameters": {
                        "environmentBaseLibrary":"A120ENV",
                        "environmentId":"DEV121A"
                }
        },
   ...
}

What are more complex situations?

In case if on one IBM i you have multiple companies for one customer, and Aperio Backend data has separate libraries per company. Then the best solution is to put Aperio Backend Data library associated to production also on the initial library list.

Example: Customer has 3 companies:

• PR - prod. Aperio Backend Data Library is: CUSTDATAPR
• CQ - test. Aperio Backend Data Library is: CUSTDATAQC
• DV - development. Aperio Backend Data Library is: CUSTDATADV

In this case the best would be to put SUCTDATAPR on the initial library list for API Bridge

{
        "environment": {
                "libraryList":"A120ENV,DEV121AS,DEV121AP,A120AP,CUSTDATAPR,IAF100AP",
                "serviceProgram": "IAFS0001",
                "initMethod": "environment.init",
                "parameters": {
                        "environmentBaseLibrary":"A120ENV",
                        "environmentId":"DEV121A"
                }
        },
   ...
}

There is also a possibility to put only IAF100AP on the initial library list without customer specific data library. In this case, you have to make sure that you have the definition of the following APIs in IAF100AP. To check it, go to 5250 and remove customer specific data library from the library list (leave only IAF100AP) and run command WRKAPIMTH. Press F8 and make sure your current metadata is located in IAF100AP. Then make sure that the following APIs are defined in IAF100AP library. If something is missing you can add it manually. These methods/programs are important to initialize job on IBM i.