Setup the MDCMS HTTP server

Published: 2025-06-16

Based on MDCMS Version 8.6.7+

Overview

What is REST?

From Wikipedia:

Representational State Transfer (REST) is a software architectural style that defines a set of constraints to be used for creating Web services. Web services that conform to the REST architectural style, termed RESTful Web services (RWS), provide interoperability between computer systems on the Internet. RESTful Web services allow the requesting systems to access and manipulate textual representations of Web resources by using a uniform and predefined set of stateless operations. Further information can be found in Wikipedia.

The MDCMS HTTP Server

MDCMS Version 8.2 and higher provides a collection of REST APIs (Web services) that can be used to share information between MDCMS and external tools via HTTP.

This server is also used for communication with MDOpen for VS Code from 8.5, MDOpen for Web from 8.6 and MDOpen for RDi from 8.7.

The server itself is installed as an instance of the native IBM http apache server, which is automatically available as part of the core OS/400 licensed program stack.

The APIs themselves are standard ILE RPG programs, which also run on any OS/400 operating system without further prerequisites. They are invoked by the http server using the native IBM CGI framework.

MDOpen in VSCode is also available as a web application. This is referred to as MDOpenweb. The HTTP server on IBM i, used to host the MDOpenweb application, is configured in the place in the MDCMS green screen application.

Setup MDCMS HTTP Servers

Managing HTTP Servers

All MDMCS HTTP servers for an instance of MDCMS on a partition are configured from the MD HTTP Servers screen. Navigate to this screen using:

Command MDCMS within a 5250 session
Option 1 - MDCMS Setup Menu
Option 10 - Interface Settings
Option 9 - HTTP Servers - lists available REST API and MDOpenweb Servers

MDCMS HTTP Servers Screen

MDCHTTP                         T86 Dev/Test                          16.06.25
SCRN1                          MD HTTP Servers                        16:03:47

Type options, press Enter.                                                    
 2=Edit  3=Copy  4=Delete  5=View  D=Default  E=End  I=IFS  S=Start           

                                Non-SSL  SSL                                  
  Instance   Type      Status    Port    Port  JobD Name  JobD Lib   Dft      
  MDCMST86   API       Running    2586         MDAPIT86   QGPL        Y

Columns

Column	Description
Instance	The HTTP server instance name.
Type	There are two types of HTTP servers used by MDCMS: API - REST API Server instance that MDCMS REST APIs are served from. MDOPENWEB Hosts the MDOpen VSCODE web application.
Status	The current run status of the server.
Non-SSL Port	HTTP Port number the server listens on. See the "warning" below this table
SSL Port	SSL Port number the serer listens on
JobD Name	Name of the job description used by the HTTP server instance which sets LIBL for the server. ONLY Applicable to type "API" servers.
JobdD Lib	Library where the HTTP server instance Job Description is found.
Dft	Specifies whether this server instance is the Default server used by MDCMS DevOps. This server will then be used by MDChange when automatically creating webhooks in Azure, Gitlab etc..

SSL/HTTPS Mandatory for MDOPENWEB servers

Communication to the MDOpenweb HTTP server and between the MDOPENWEB web application and the MDChange REST API servers, MUST be using HTTPS scheme.

This can be configured by making the MDOPENWEB HTTP server instance run directly under SSL/HTTPS. Or the server can be run as HTTP, but then it must be run behind a reverse-proxy server that IS configured to run SSL/HTTPS.

See here for more details about setting up a reverse-proxy server.

Options

Option	Description
2=Edit	Edit the selected server configuration.
3=Copy	Copy the selected server configuration.
4=Delete	Delete the server instance and its related IFS folders.
5=View	Display the server configuration, including a test URI.
D=Default	Make this server the default API server for MDCMS DevOps webhooks.
E=End	End the HTTP Server Instance.
S=Start	Start the HTTP Server Instance.

Command-Function Keys

Commands	Description
F3	Exit to the previous screen
F5	Refresh the screen to see the current Status
F6	Add a new server instance of type API or MDOPENWEB
F8	Show all jobs running under QHTTPSVR subsystem
F10	Runs command `NETSTAT *CNN` which lists all port numbers currently being used on the IBM i partition
F21	Opens a command line screen (as per CALL QCMD)

Adding a REST API Server

From the MDCMS HTTP Servers Screen, select command key F6

Adding a new HTTP Server

MDCHTTP                         T86 Dev/Test                          16.06.25
SCRN2                       Add an MD HTTP Server                     15:54:12


Server Type:    1=MDCMS API Server (Apache)                                   

                3=MDOpen for Web Server (Apache)                              


NOTE: An MDCMS API Server is a pre-requisite for using MDOpen for RDi,        
      MDOpen for VS Code or MDOpen for Web.                                   
...

Enter=Continue   F12=Cancel

Use option 1 to create a new MDCMS REST API server instance, and press enter.

Create a new MDCMS REST API server instance

 MDCHTTP                         T86 Dev/Test                          16.06.25
 SCRN3                      Create MDCMS API Server                    15:58:21

 Server Name . . . . . . MDCMST86                                              

 Non-SSL Port Number . .                                                       
 SSL Port Number . . . .                                                       
 DCM Application . . . .                                                       

 Job Description . . . . MDAPISVR      Will auto-create, if new                
   Library . . . . . . .   QGPL                                                

Server URL                                                                     
https://this-partition.com                                                     

Enter=Confirm   F4=Browse   F12=Cancel   F12=Sys Command

Parameter	Description
Server Name	The name of the Server to create. The server will be replaced if it already exists. Normally, only one server should be active for a given instance and partition of MDCMS. When created, the server configuration will be placed in IFS folder /www/<server name>
Non-SSL Port Number	The port number that the server should listen to for incoming insecure http requests. *NONE - an insecure port should not be configured. Port number - a number up to 5 digits that isn't used by any other server on the partition.
SSL Port Number	The port number that the server should listen to for incoming https requests. *NONE - an SSL port should not be configured. Port number - a number up to 5 digits that isn't used by any other server on the partition.
DCM Application	The name of an Application in the *SYSTEM certificate store that is assigned to the preferred SSL certificate. This is only necessary when configuring an SSL port. creating a DCM Application
Job Description/Library	The name and library of the job description that contains the MDCMS product library list (MDCMS(env), MDREP(env), MDSEC(env) and MDXREF(env)) as well as the ASP Device name that the libraries reside in If the job description doesn't exist, MDCMS will automatically create it
Server URL	The server URL is the address of the partition, including the transport method: http or https. Don't include the context path in the endpoint. Example: `https://devbox.mycompany.com` When a REST request is sent to the endpoint, it will then be followed by the name of the mdcms instance (usually mdcms) and then the resource name of the API to be invoked. Example: to get a list of all applications defined in MDCMS: https://devbox.mycompany.com/mdcms/applications

When Enter is pressed, the server is created and automatically started. The MD HTTP Servers screen will update and show the REST API server added to the list:

MDCMS REST API server added to servers

MDCHTTP                         T86 Dev/Test                          16.06.25
SCRN1                          MD HTTP Servers                        16:03:47

Type options, press Enter.                                                    
 2=Edit  3=Copy  4=Delete  5=View  D=Default  E=End  I=IFS  S=Start           

                                Non-SSL  SSL                                  
  Instance   Type      Status    Port    Port  JobD Name  JobD Lib   Dft      
  MDCMST86   API       Running    2586         MDAPIT86   QGPL        Y

Verify MDMCS REST API Server is Running

To check if the server is running, select option 5 against the newly added API server, from the MD HTTP Servers screen.

    MDCHTTP                         T86 Dev/Test                      16.06.25
SCRN3                         MDCMS API Server                        16:15:14

Server Name . . . . . . MDCMST86                                              

Non-SSL Port Number . .  2586                                                 
SSL Port Number . . . .                                                       
DCM Application . . . .                                                       

Job Description . . . . MDAPIT86      Will auto-create, if new                
Library . . . . . . .   QGPL                                                

Server URL                                                                     
https://dev.mdcms.ch                                                           

Example API Request                                                            
https://dev.mdcms.ch/MDCMST86/applications                                     

F3=Exit

Click on the Example API Request link

Your internet browser should open, and if the server is running, it should return a list of MDCMS Applications that have been configured. For example:

{
  "applications": [
    {
      "appl": "ADM",
      "desc": "Administration tests"
    },
    {
      "appl": "SYNON",
      "desc": "Synon/2E application"
    },
    {
      "appl": "CUSTO1",
      "desc": "Custom objects App1"
    }
  ]
}

If the application json list is not returned, return to the previous MDCMS API Server 5250 screen, select F3 to exit.

Review the status of the server.

Troubleshooting connectivity to MDCMS HTTP server

If there are connectivity problems, try this MDCMS Connectivity Troubleshooting knowledge guide.

Additional Requirement for MDOpen VSCode

The OpenSSH server must be active and available through any firewall on each IBM i partition that this extension will connect to.
The Code for IBM i extension from Halcyon Tech should also be installed, though connections do not have to be created in the Code for IBM i extension for MDOpen to function, as MDOpen creates its own connections.

Adding an MDOPENWEB Server

Note

The MDOPENWEB configuration screen requires the input of the REST PI server details added previous. Therefore ensure the REST API server is installed and running

From the MDCMS HTTP Servers Screen, select command key F6

Adding a new HTTP Server

MDCHTTP                         T86 Dev/Test                          16.06.25
SCRN2                       Add an MD HTTP Server                     15:54:12


Server Type:    1=MDCMS API Server (Apache)                                   

                3=MDOpen for Web Server (Apache)                              


NOTE: An MDCMS API Server is a pre-requisite for using MDOpen for RDi,        
      MDOpen for VS Code or MDOpen for Web.                                   
...

Enter=Continue   F12=Cancel

Use option 3 to create a new MDOPENWB server instance, and press enter.

Create a new MDCMS REST API server instance

 MDCHTTP                         T86 Dev/Test                          17.06.25
 SCRN3                   Create MDOpen for Web Server                  19:24:50

 Server Name . . . . . . MDOPWT86                                              

 Non-SSL Port Number . .                                                       
 SSL Port Number . . . .                                                       
 DCM Application . . . .                                                       

 MDCMS Environment . . . T86                                                   
 MDCMS API Server Host . dev.mdcms.ch                                          

 MDCMS API SSL Port  . .   443                                                 

Server URL                                                                     
https://dev.mdcms.ch 

 Enter=Confirm               F12=Cancel   F12=Sys Command

Parameter	Description
Server Name	The name of the Server to create. The server will be replaced if it already exists. Normally, only one server should be active for a given instance and partition of MDCMS. When created, the server configuration will be placed in IFS folder /www/<server name>
Non-SSL Port Number	The port number that the server should listen to for incoming insecure http requests. *NONE - an insecure port should not be configured. Port number - a number up to 5 digits that isn't used by any other server on the partition.
SSL Port Number	The port number that the server should listen to for incoming https requests. *NONE - an SSL port should not be configured. Port number - a number up to 5 digits that isn't used by any other server on the partition.
DCM Application	The name of an Application in the *SYSTEM certificate store that is assigned to the preferred SSL certificate. This is only necessary when configuring an SSL port. creating a DCM Application
MDCMS Environment	The Instance name that MDCMS runs under
MDCMS API Server Host	The host name or IP address that exposes the MDCMS REST APIs. See Managing HTTP Servers above for details on the REST API server
MDCMS API SSL Port	The SSL port number used to host the MDCMS REST API server. Thsi can be directly configured in the MDCMS REST API server instance, or behind a reverse-proxy server.
Server URL	The server URL is the address of the partition, including the transport method: http or https. Don't include the context path in the endpoint. Example: `https://devbox.mycompany.com` When a REST request is sent to the endpoint, it will then be followed by the name of the mdcms instance (usually mdcms) and then the resource name of the API to be invoked. Example: to get a list of all applications defined in MDCMS: https://devbox.mycompany.com/mdcms/applications

When Enter is pressed, the server is created and automatically started. The MD HTTP Servers screen will update and show the REST API server added to the list:

MDOPENWEB server added to servers

MDCHTTP                         T86 Dev/Test                          17.06.25
SCRN1                          MD HTTP Servers                        19:41:18

Type options, press Enter.                                                    
 2=Edit  3=Copy  4=Delete  5=View  D=Default  E=End  I=IFS  S=Start           

                                Non-SSL  SSL                                  
  Instance   Type      Status    Port    Port  JobD Name  JobD Lib   Dft      
  MDCMST86   API       Running    2586         MDAPIT86   QGPL        Y       
  MDOPWT86   MDOPENWEB Running            2571                        Y

Verify MDOpenweb Server is Running

To check if the server is running, in the web browser type in :

https://your_hostname:ssl_port

You should be presented with the login screen for MDOpenweb