Configure the MDCMS HTTP Server

Published: 2025-01-22

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.

Configure the MDCMS HTTP Server

Generate the Server

To create the server for an instance of MDCMS on a partition:

command MDCMS within a 5250 session
Option 1 - MDCMS Setup Menu
Option 10 - Interface Settings
Option 9 - MDCMS HTTP Server
Option 2 - Generate Server

MDCGRAS                         T86 Dev/Test                          22.01.25
SCRN1                 Create/Update MDCMS HTTP Server                 14:44:43


Server Name . . . . . . MDCMST86MM                                            

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

Non-SSL Port Number . . 2999                                                  

SSL Port Number . . . . *NONE                                                 

DCM Application . . . . __________________________________         


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>
Job Description	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
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

When Enter is pressed, the server is created and automatically started.

Verify Server is Running

To check if the server is running, use command :WRKSBSJOB QHTTPSVR.

If the server is running, several jobs that are named the same as the Server (usually MDCMS) will be in ACTIVE status.

If not running, use STRTCPSVR SERVER(*HTTP) HTTPSVR(<server name>) to start.

If still not running, then WRKLNK '/www/<server name>/logs' to troubleshoot the problem.

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.

STOP and START or RESTART MDCMS HTTP Server

The server can be stopped with command ENDTCPSVR SERVER(*HTTP) HTTPSVR(MDCMS) assuming MDCMS is the name of the server.

The server can be started with command STRTCPSVR SERVER(*HTTP) HTTPSVR(MDCMS) assuming MDCMS is the name of the server.

Note

It’s recommended to configure the server to autostart (in the IBM i HTTPAdmin UI) or to add the command to the QSTRUPPGM instructions.

Set up Reverse-Proxy to Forward REST Service Requests from Default HTTP Server

It is recommended to proxy all requests to the MDCMS server through the default http server on the partition because:

no need to indicate the port number in the URL
no need to add another port number to the firewall rules
potentially take advantage of existing SSL configuration in the default http server

To configure the proxy:

use WRKLNK to navigate to the /www location of the default server (usually named APACHEDFT)
view the conf directory
edit the httpd.conf file

ensure the following modules are listed in the configuration. If missing then insert them into the configuration:

LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM 
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM 
LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM 
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM 
LoadModule proxy_balancer_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

add the following 3 lines to the configuration:
```
ProxyPreserveHost On 
ProxyPass /mdcms/ http://localhost:1901/mdcms/ 
ProxyPassReverse /mdcms/ http://localhost:1901/mdcms/
```
Replace 1901 with the port number you specified for the server mdcms is correct if the instance of MDCMS is MDCMS. If your instance is TEST for example, then replace all 4 occurrences of mdcms with mdcmstest. NOTE: mdcms in the URL is always the instance of MDCMS, regardless of the name of the server.
save the configuration and restart the default server

Define the URL to reach the MDCMS Server

MDCMS needs to be aware of the URL to the server in order to set up WebHooks for certain external servers such as JIRA. To define the URL:

command MDCMS within a 5250 session
Option 1 - MDCMS Setup Menu
Option 10 - Interface Settings
Option 9 - MDCMS HTTP Server
Option 1 - Set/Change URL

The Endpoint 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

Test Connection to the MDCMS REST APIs

The simplest test, if your PC has access to the IBM i, is to open a browser and enter the following in the address prompt:

https:///mdcms/applications

replacing with the endpoint defined in your MDCMS settings.

If not using the default instance of MDCMS, replace mdcms with the name of the instance in lowercase.

If not using https, replace https with http.

If the test works, you'll see a list of your applications in JSON format. NOTE: From MDCMS 8.5 onwards, an API Token is required to authenticate a request to the REST APIs. If the connection test works, you will get a Status 401 with message "API Token not found" in the response body.

For more elaborate tests of the various services, including being able to include an API Token, we recommend the use of Postman or SoapUI.

Tip

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