In OpenApi we have special places where Aperio specific elements can be defined. These sections are defined as “x-aperio”. Mainly there are two sections where “x-aperio” may exist.
“x-aperio” on http method level is to define which program must be bun on IBM i whenever someone calls this API http method.
Example of OpenAPI specification…. See at the very end how “x-aperio” is defined
"paths" : {
"/actors" : {
"get" : {
"tags" : [ "Aperio test" ],
"summary" : "Get list of actors",
"description" : "Get list of actors",
"parameters" : [ {
"name" : "firstName",
"in" : "query",
"schema" : {
"$ref": "#/components/schemas/firstName"
}
}, {
"name" : "lastName",
"in" : "query",
"schema" : {
"$ref": "#/components/schemas/lastName"
}
}, {
"name" : "age",
"in" : "query",
"schema" : {
"$ref": "#/components/schemas/age"
}
}, {
"name" : "weight",
"in" : "query",
"schema" : {
"$ref": "#/components/schemas/weight"
}
}, {
"name" : "dateOfBirth",
"in" : "query",
"schema" : {
"$ref": "#/components/schemas/dateOfBirth"
}
}, {
"name" : "active",
"in" : "query",
"schema" : {
"$ref": "#/components/schemas/active"
}
}, {
"$ref" : "#/components/parameters/control-limit"
}, {
"$ref" : "#/components/parameters/control-offset"
}, {
"$ref" : "#/components/parameters/control-orderBy"
}, {
"$ref" : "#/components/parameters/control-freeTextSearch"
} ],
"responses" : {
"200" : {
"description" : "OK",
"$ref": "#/components/responses/actors"
},
"4xx" : {
"description" : "Client error",
"$ref" : "#/components/responses/default-error"
}
},
"x-aperio" : {
"control-parameters" : {
"openCrossRef" : false,
"program" : "IAFRT001",
"httpMethod": "GET"
}
}
},
"post" : {
"tags" : [ "Aperio test" ],
"summary" : "Add actor",
"description" : "Add actor",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "id", "firstName", "lastName", "age", "weight", "dateOfBirth", "active" ],
"type" : "object",
"$ref" : "#/components/schemas/actor"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "OK"
},
"4xx" : {
"description" : "Client error",
"$ref" : "#/components/responses/default-error"
}
},
"x-aperio" : {
"control-parameters" : {
"openCrossRef" : false,
"program" : "IAFRT001",
"httpMethod" : "POST"
}
}
}
}
The x-aperio is an object which contains inner object named “control-parameters”. Inside it you may define which RPG program to run on IBM i.
"x-aperio" : {
"control-parameters" : {
"openCrossRef" : false,
"program" : "IAFRT001",
"httpMethod" : "POST"
}
}
The definition above tells what and how will be run on IBM i:
List of predefined elements of “x-aperio” object you can find here:
| key | type | example value | description |
|---|---|---|---|
| control-parameters | object | - | container for all RPG program related parameters |
| control-parameters.program | string | “MGRR001” | RPG program name |
| control-parameters.method | string | “items.get” | API method name. It is still possible to use method name instead of RPG program name. If program name is provided the method name is ignored. |
| control-parameters.openCrossRef | boolean | true | bollean value indicationg if crossref must be open prior RPG program call or not. |
| control-parameters.openFiles | string | “SRONAM, SRONOI” | Coma separated file names that need to be open prior RPG program call. Either openCrossRef or openFiles can be used |
Beside above hardcoded parameters any other parameter can be entered there. It will be included in RPG call. See examples bellow.
Example 1: Call program and openCrossRef
"x-aperio" : {
"control-parameters" : {
"openCrossRef" : true,
"program" : "MGRR001"
}
}
This will produce the following request to call the RPG program:
{"control":{"program":"MGRR001", "openCrossref":true}, "params":.......}
Example 2: Call method and do not openCrossRef
"x-aperio" : {
"control-parameters" : {
"openCrossRef" : false,
"method" : "items.get"
}
}
This will produce the following request to call the RPG program:
{"control":{"method":"items.get", "openCrossref":false}, "params":.......}
Example3: Method and program are provided
"x-aperio" : {
"control-parameters" : {
"openCrossRef" : false,
"method" : "items.get",
"program" : "MGRR001"
}
}
This will produce the following request to call the RPG program. As you see both program and method are sent but only program will be taken into consideration by the aperio backend:
{"control":{"method":"items.get", "program":"MGRR001", "openCrossref":false}, "params":.......}
Example4: Extra hardcoded parameters are added to “x-aperio”
"x-aperio" : {
"control-parameters" : {
"openCrossRef" : false,
"program" : "MGRR001",
"myControlPar1" : "abc",
"mySecondPar" : 123,
"myThirdPar" : false
}
}
This will produce the following request to call the RPG program. As you see all hardcoded params were added to “control” section for RPG program.
{"control":{"program":"MGRR001", "openCrossref":false, "myControlPar1" : "abc", "mySecondPar" : 123, "myThirdPar" : false}, "params":.......}
The second place to use “x-aperio” is on the parameters level in OpenAPI spec. At this level You have possibility to decide how HTTP parameter wil be named in RPG call and where it should be put: to “params” or to “control” section. Bellow is an example of using “x-aperio” in the parameter section.
"/test/{pathPar1}/{pathPar2}" : {
"parameters": [
{
"name": "pathPar1",
"in": "path",
"x-aperio": {
"name": "renamedPathPar1",
"in": "control"
},
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "pathPar2",
"in": "path",
"x-aperio": {
"name": "renamedPathPar2",
"in": "params"
},
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "queryPar1",
"in": "query",
"x-aperio": {
"name": "renamedQueryPar1",
"in": "control"
},
"schema": {
"type": "string"
}
},
{
"name": "queryPar2",
"in": "query",
"x-aperio": {
"name": "renamedQueryPar2",
"in": "control"
},
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "queryPar3",
"in": "query",
"x-aperio": {
"name": "renamedQueryPar3",
"in": "params"
},
"schema": {
"type": "boolean"
}
}
],
"get" : {
"tags" : [ "Aperio test" ],
"summary" : "Get request",
"description" : "Get request",
"responses" : {
"200" : {
"description" : "OK"
},
"4xx" : {
"description" : "Client error",
"$ref" : "#/components/responses/default-error"
}
},
"x-aperio" : {
"control-parameters" : {
"program" : "TEST001",
"hardcodedPar1" : "ccc",
"hardcodedPar2" : 999,
"hardcodedPar3" : false
}
}
}
}
The definition above controls pathPar1 and pathPar2 in the following way:
Additionally there are 3 query parameters and they will also be renamed and put to control and params sections accordingly. This is how the RPG call will look like. Note, that there are also 3 hardcoded parameters passed to “control” section.
If the HTTP request look like this:
GET: http://server:port/rest/suffix/1/test/abc/123?queryPar1=ZZZ&queryPar2=999&queryPar3=true
The request to the RPG may look like this…
{
"control":{
"program" : "TEST001",
"hardcodedPar1" : "ccc",
"hardcodedPar2" : 999,
"hardcodedPar3" : false,
"renamedPathPar1": "abc",
"renamedQueryPar1": "ZZZ",
"renamedQueryPar2": 999
},
"params":{
"renamedPathPar2": 123,
"renamedQueryPar3": true
}
}
The list of the predefined elements of “x-aperio” object you can find here:
| key | type | example value | description |
|---|---|---|---|
| name | string | “myname” | the name of the parameter which to be passed to RPG program |
| in | string | “control” or “params” | Decide the location of the parameter in the request |
In OpenAPI specification for base ERP API we have defined a number of predefined special parameters. These are common for all APIs.
NOTE: Not all APIs support every parameter. See OpenAPI definition to understand what APIs support which parameters.
| Parameter | type | section in RPG call | meaning |
|---|---|---|---|
| freeTextSearch | string | control | Control parameter used by number of APIs to free search through rows in database. |
| offset | string | control | Control parameter to set offset when retrieving data from table, usually combined with a limit |
| limit | integer | control | Control parameter to limit the number of rows fetched from database |
| orderBy | string | control | Control parameter by which you can decide the response should be sorted by. The value is a list of fields coma separated. It can also contain ASC or DESC after space. If sort order is not provided then by default is ASC. Example: “orderBy” :“item, description DESC, customer ASC” |
| fields | string | control | Control parameter which can be used to create a subset of response data. This is a list of fields that will be selected from the original set. For example if RPG program produces 100 of collumns in response you can decide that only two of them will be in response. “fields”:“item, description” |
| accept-response | string | control | Control parameter which can be used to create a subset of the response from RPG program. For example, value “data” will tell aperio that you only accept “data” object in response. Even if RPG program produces something else only “data” will pe passed through Aperio |