API Bridge

API Bridge is container solution which joins IBM i with HTTP world. It is used to convert HTTP requests into Iptor internal IADF (Iptor API Data Format), then it calls RPG program. The response generated by RPG program is converted back to HTTP response. API Bridge allows to publish RPG backend programs as REST services. API Bridge plays several roles in the API landscape:

• HTTP <-> IADF (Iptor API Data Format) interpreter
• Authorizes HTTP requests by checking incoming requests with external authentication provider (currenty Keycloak)
• Session handling with job pooling. Creates and configures IBM i sessions.
• Exposes REST Web Services based on OpenAPI specification. Regardless how many RPG programs exist on IBM i backend, API Bridges exposes only these which are included in OpenAPI specification. See OpenAPI driven API
• Additionally, has a built-in mechanism to read RPG program and generate OpenAPI specification for it.

Endpoints

Below is the list of endpoints that are exposed by API Bridge (only summary information provided). For more information, see Core OpenApi specification.

/rpc (legacy)

This group of endpoints are used to communicate within internal infrastructure of Iptor objects (legacy). It is also used by Aperio Client (generated mobile apps).

/rpc-oidc

New version of RPC connection prepared to handle token generated by Keycloak. All APIs require Authorization header with Bearer Keycloak token as value. Additionally they require to provide Env-Company as HTTP header. Example: Env-Company=DV.

/health

This group of endpoints may be used for health check of API Bridge.

/admin

This group of methods are used to maintain API Bridge. They are allowed only for aunthenticated users (Keycloak). Additionally, users must have role “admin”. All endpoints require Authorization header with Bearer token (Keycloak) as value.

/rest

This group of endpoints are exposing API according to OpenAPI specification. For details how the path is constructed see Rest endpoints construction mechanism.

/rest-alt

Alternative REST path where API version is passed via header (API-Version). The construction of path is similar to the one described here but without version in the path.

Configuration

Full confoguration description you can find also here

The following environmant variables are used to configure API Bridge:

The configuration file is a simple json file which contains pairs of variable:value. Some of the parameters from config file can be provided as environment variables. In this case the highest priority has the environment variable value. If not provided, then the confg file value is taken.

Note: The configuration file consists of some elements that belong to DC1 environment and some are related to API bridge sessings.

Example of config file:

{
        "environment": {
                "libraryList":"A120ENV,DEV121AS,DEV121AP,A120AP,IAF100AP",
                "serviceProgram": "IAFS0001",
                "initMethod": "environment.init",
                "parameters": {
                        "environmentBaseLibrary":"A120ENV",
                        "environmentId":"DEV121A"
                }
        },
        "serverTLS":false,
        "defaultUserId":"",
        "defaultUserPassword":null,
        "serviceUserId":"aperio_srv",
        "serviceUserPassword":"",
        "jobCCSID":0,
        "serverAddress":"smibsrd0.ibs.net",
        "maxJobsPerConnection":50,
        "openAPIConfigs":[
                {
                        "pathSuffix": "base",
                        "oasFiles": ["http://dkdcvs134.ibs.net:779/doc/v1/iptor-erp-api.json"]
                },
                {
                        "pathSuffix": "base-test",
                        "oasFiles": ["api/config/api/aperioTest.json"]
                }
        ],
        "environmentSelectionForm": "",
        "jwtKey": "abc45678901234567890123456789012",
        "tokenTimeout" : 36000,
        "refreshTokenTimeout" : 604800,
        "aperio.gen.config": "/api/config/api/generator.json"
}

It is reccomended to use configMaps to inject environment variables to containers (direct valurd or as JSON file). For user and password the best practice is to use secrets.

REST endpoints construction mechanism

Generally API Bridge exposes REST APIs from “rest” endpoint, but a number of elements are added to the path based on OpenAPI specification. The following pattern is used to construct REST API endpoints:

{server}:{port}/rest/{pathSuffix}/{version}/{pathsFromOpenApi}

where: pathSuffix - provided in config file connected to OpenAPI specification version - taken from OpenAPI specification - the major element of “version” value.

Example: Let assume following config.

{
    "openAPIConfigs":[
        {
                "pathSuffix":"base",
                "oasFiles":["myfile.json"]
        }
    ]

}

Then myFile.json contains following entry:

{
  "openapi" : "3.0.0",
  "info" : {
    "version" : "1.2.3",
    "title" : "Example OpenAPI spec",
  },
  "paths" : {
    "/areas" : {
        ...
}        

then the elements will get following values: pathSuffix = “base” version = “1”

The URL will be as follows: http://dkdcvs134.ibs.net:8080/rest/base/1/areas