Provider Path Tab

Screen Layout

The screen below appears when editing a Provider spec and the "Path" tab is selected.

Each section controls a different aspect of OAPI/SWAGGER editing, and providing details for the RPG/COBOL generators.

Path Header

Select a path

The Paths are shown in the dropdown list on the left hand side.

Add a New Path

Click the button to add a New path.

Click the button, and the path is added to the underlying OAPI/SWAGGER, and the dropdown list updated.

Delete a path

Click the button to delete the selected path.

Select "Yes" to delete the path.

Edit a path name

To change the pathname, click the pencil icon in the button bar. A popup window appears on click.

Make the necessary changes and press the Update button. This will update corresponding in the underlying OAPI/SWAGGER.

Adding Path Parameters

Path parameters can be added to the path name by enclosing the path parameter in curly braces as shown in the example below:

Click and the paths list gets updated as:

This will add an in: Path parameter to the requests section of the underlying OAPI/SWAGGER:

- in: path
  name: id
  description: id description
  required: true
  schema:
    type: string

This parameter will also appear in the HTTP Options when the parameters button is selected:

This tells the generator to add code in the provider program, to extract the value of the path parameter:

// Get Path Parameters                                                                           
if MDR_getPathVar(handle: 'myapiname':1) <> '*NOTFOUND';                                         
  pthparm2 = MDR_getPathVar(handle: 'myapiname':1);                                              
else;                                                                                            
  errorMsg = 'Mandatory path parameter: pthparm2 not supplied';                                  
  MDR_setError( handle: 'API0002': errorMsg: 10000: 20 : 400);                                   
  *Inlr = *On;                                                                                   
  Return;                                                                                        
Endif;

Path Header Options

This section below the path editing line, includes more details for the selected path. These details correspond to the "x-mdrGen" object in the OAPI section of the selected path.

Option	Description
Description	A text description of the path. This description is used to as the text for the generated source member and object.
Gen Template	Specifies which generation template is used to generate the code in what language. RPGLE_EACH - One program per path per HTTP method is generated in RPG Free. COBOL_DFT - One program per path per HTTP method is generated in ILE COBOL.
Program	This is the IFS formatted path to the Library/object name of the prgram to be generated. The library and object names can be edited using the popup. EXAMPLE: /QSYS.LIB/YOURLIB.LIB/APIPGM.PGM
JWT	Specifies if generator should add logic to retrieve and validate the Authorization header using MDRest4i JWT functions.

HTTP Methods

Shows the lists of HTTP methods as different tabs

Enable Method

To enable additional methods, select the method required and, if this method is not found in the OAPI/SAWGGER for this path, select the Enable xxxx Method button for that method:

This will add this method, with default values from the provider template for that method, to the OAPI/SWAGGER and update the screen, to show Generation Options for that method.

Generation Options for Provider

All these values are added/edited in the "mdrGenOptions" object of the selected method inside for the "x-mdrGen" object for the selected path.

Generation Options for a Provider

Summary

Short description of the API path. Used for documentation purposes only.

Object Path

This is the IFS formatted path to the Library/object name of the API. The library and object names can be edited using the popup.

EXAMPLE: /QSYS.LIB/YOURLIB.LIB/APIPGM.PGM

Source Path

Location of source file/mbr for the Provider program.

EXAMPLE /QSYS.LIB/STUART13.LIB/EXAMPLE.FILE/API002.MBR

Copybook Path

Location of copy book source file/mbr for payloads. The generator will create all payload data structures in this copybook, and add the /copy statement to the copybook in the generated provider.

EXAMPLE /QSYS.LIB/STUART13.LIB/EXAMPLE.FILE/API002.MBR

Description

Description of the selected method for that Provider

Payload Format

This can be JSON, XML, or TXT. The generator will create logic to write or parse the correct payload syntax

Parse Method

Determines what parsing functions are used to process the inbound payload in the generated code. Select DATA-INTO, JPATH(used for mdr_JSONPATHV etc), or IFS.

If IFS is selected, the path can be entered using the button.

This will display a popup that allows the adding of path name to the IFS object to be used in the program.

Gen Method

Determines how the outbound payload is handled in the generated code.

Select DATA-GEN, MDR-YAJL(used for mdr_addchar() etc), or IFS.

If IFS is selected, the values can be entered using the button.

This will display a popup that allows the adding of path name to the IFS object to be used in the program.

Call Type

Generator creates logic for calling a module/program/service-program from a provider. Options available: none, Program, Module, Service Program

Selecting any option other than "none", enables the button which can be used to enter the details used by the generator to create the call logic.

Each of the call types specified below allows the entry of what to call, and what parameters should be passed with the call.

The provider generator will add the necessary prototypes, bindings and calls to these objects.

Each type shows a different popup, and generates different code in the provider program: - Program - Module
- - Service Program

Program

The code generated for a program call is as follows:

dcl-pr APICALLPGM Extpgm('APICALLPGM');
  *n like(title);
  *n like(surname);
  *n like(x_surname);
end-pr;
...
callp(e) APICALLPGM(title:surname:x_surname); 

Module

The code generated for the call is as follows:

dcl-pr CALLMYPROC Extproc('CALLMYPROC');
  *n like(title);
  *n like(surname);
  *n like(x_surname);
end-pr;
...
callp(e) CALLMYPROC(title:surname:x_surname); 

Service Program

The code generated for the call is as follows:

dcl-pr CALLMYPROC Extproc('CALLMYPROC');
  *n like(title);
  *n like(surname);
  *n like(x_surname);
end-pr;
...
callp(e) CALLMYPROC(title:surname:x_surname); 

Adding Call Parameters

Provider parameters including query, path and headers can be passed to the called pgm/mod/srvpgm. The SDK generator will add logic to extract these parameters, and assigns them to the call wheer specified

Add these using the select parameters button.

When this is clicked, any inbound parameter defined for this path and method (including query parameters, headers and path parameters) will be displayed as a list from which any can be selected. For example:

Once selected and confirmed with the button, the screen is updated, and the underlying OAPI/SWAGGER is updated in mdrGenOptions for that method:

These parameters can be removed individually using the , while the parameter is selected in green.

Passing Request Schema

The request body schema (POST, PUT, PATCH methods) can be passed as a parameter to the called program/procedure.

This adds the request body data structure (created from the request body schema) to the end of the call to the specified program/module/service pgm.

Method Options

For the Get & Delete Methods, the following buttons appear:

Other methods (POST, PUT, PATCH) display the following buttons:

Option	Description
Parameters	Select to display and edit request parameters
Body	Select to display and edit request body details. (only for POST, PUT, PATCH method requests)
Responses	Select to display and edit response body details.
Tags	To create tags
Object Request	For MDCMS users. This appears only if “Object Required" box is checked in the Edit Site

Parameters

Click on the button

To adda new parameter, click on the link

A new popup window appears

Select the scope (query/header). Enter the parameter name and description and click

The "Paths" tab screen now looks like:

The schema can be selected from the dropdown list of schemas created using the schema tab.

On selecting the schema, the list of fields automatically is displayed in the next input field, Schema Field.

The Swagger definition now adds the "parameters" field .

Here, the Swagger Extension fields x-schema, x-schemaFld are used.

In case of "header" type parameters, an additional input "flow" is required.

The Swagger Extension field x-flow is used which can have the value "in", "out" or "both" depending on the boxes checked.

Body

Click on the button to edit the request body. The "Body" option is available only for "POST", "PUT" and "PATCH" methods.

When this button is selected the “requestBody” section appears. Identical to the response section, it allows the request body schema and format to be selected. There are no parameters required for POST, PATCH, or PUT methods in REST style, although it is not forbidden and sometimes parameters are used with these methods.

When no request body has been created, the section looks like:

Click on the button to create one.

Click

Select the Content Type as application/json from the dropdown list.

Select the Model type from the dropdown provided which lets you select if the type: allOf, anyOf, oneOf, if you wish to combine schemas.

• oneOf – validates the value against exactly one of the subschemas
• allOf – validates the value against all the subschemas
• anyOf – validates the value against any (one or more) of the subschemas

Selecting none lets you select a single schema.

Selecting oneOf, allOf, anyOf brings up the entry fields to select/deselect the multiple schemas and the multiple no-schema reference objects too. Click the button to close the dropdown list.

Select the schemas and no schema references, if any.

The following object: requestBody is added to the swagger.

Select the schema from the dropdown list which shows the list of schemas created in the schema tab.

Following object: requestBody is added to the swagger.

Responses

By default, four HTTP responses are added to each API. Response 200 is the default status header field and value, which tells the requesting browser or consumer, that everything is OK.

From the “Responses” section on the right hand side, select the content type, Model Type and then select a schema(s) created earlier from the Schema drop down depending on the model type selected.

The "responses" object is updated like so:

For model type other than "none":

The "responses" object is updated like so:

Tags

The "tags" array is now added to the Swagger definition.

Use the button to create more tags. The first one is created by default and takes the program name.

Object Request

When selected the dynamic dialogue below appears. The fields are initialised with the default values fetched from the IBMi server using the Rest API.

Click

This updates the swagger spec as per the section below:

Read more about x-mdcms here

The values can be edited and saved.

The changes to

now which lets you modify the object definition anytime.

Helper buttons

MDRest4i supports iAsp, IFS and Source file options for compilation.

To allow for this a member APIPGM in source file QRPGLESRC in library APISRCLIB, must be entered using this IFS syntax:

/QSYS.LIB/APISRCLIB.LIB/QRPGLESRC.FILE/APIPGM.MBR

The same source file in the folder APISRC would use this syntax:

/APISRC/APIPGM.RPGLE

Using this format, an object path would look like this:

/QSYS.LIB/YOURLIB.LIB/APIPGM.PGM

For those users not familiar with this syntax for lib/file/member or objects, a popup has been created.

This popup allows the traditional manner of editing these details.

Unless you aer using a specific iASP, this value can be left blank for *SYSBAS iASP.

The previous form and underlying OAPI/SWAGGER are updated saved after the Done button is clicked.