Skip to content

Configure the MDCMS REST API Server

Published: 2024-05-15

Available from MDCMS Version 8.2

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 REST API 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.

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.

Prerequisites

  • MDCMS with a minimum version of 8.5.2 must be installed on each IBM i partition that this extension will connect to.
  • A valid MDOpen license must be active on each IBM i partition that this extension will connect to.
  • You have a user profile and are registered in MDSEC on each IBM i partition that this extension will connect to.
  • The MDCMS REST API and Diagramming Server, which is an Apache http server, must already be generated, active and available through any firewall on each IBM i partition that this extension will connect to.

Configure the MDCMS REST Server

Generate the Server

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

  1. command MDCMS within a 5250 session
  2. Option 1 - MDCMS Setup Menu
  3. Option 10 - Interface Settings
  4. Option 9 - MD REST API Server
  5. Option 2 - Generate Server
MDLGRAS                            MD Dev                             16.05.24
SCRN1                    Generate MDCMS HTTP Server                   17:42:04


Server Name . .  MDCMS                                                        

Port Number . .  _________                                                             

F3=Exit   F6=Messages   F8=Submitted Jobs   F11=View Output   F21=Sys Command
Server Name The name of the Server to create. The server can't already exist. 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>
Port Number The port number that the server should listen to for incoming http requests. The port number is mandatory and should not be attributable to any other server on the partition.

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

Tip

It is highly recommended to add the following command to the QSTRUP program so that the server will automatically restart after an IPL:

STRTCPSVR SERVER(\*HTTP) HTTPSVR(<server name>)

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.

Set up MDCMS HTTP Server to use HTTPS (TLS/SSL)

HTTPS connectivity for the MDCMS REST API's can be achieved in one pf two ways:

  1. Directly configuring the MDCMS HTTP server instance to use HTTPS(TLS/SSL).
  2. Via a Proxy server instance (described below) where the Proxy server instance is HTTPS enabled. This approach will enable multiple HTTP server instances to use a single HTTPS configuration

HTTPS requires TLS/SSL to be set up on the IBM i server, before an HTTP Server instance can be HTTPS enabled. If SSL is already in use on your IBM i, you can jump to the second step below:

  1. Setup TLS/SSL on the IBM i
  2. Enable an HTTP server instance for HTTPS

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:

  1. use WRKLNK to navigate to the /www location of the default server (usually named APACHEDFT)
  2. view the conf directory
  3. edit the httpd.conf file
  4. 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
  5. 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.
  6. 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:

  1. command MDCMS within a 5250 session
  2. Option 1 - MDCMS Setup Menu
  3. Option 10 - Interface Settings
  4. Option 9 - MD REST API Server
  5. 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.