m-Power Web Services

 

Intro
Set Up
Getting Data
CRUD Actions
Promoting
Notes

Introduction

A very common feature of modern web applications is an API that can be accessed from outside the framework for use in any architecture. m-Power has implemented such an API using RESTful web services, now available in supported templates. For more regarding REST, please see this link.

Set Up

Applications are set up exactly the same for both web services and standard applications. Apps must be compiled/recompiled with the precompile option set to include web services. In the screenshot below, this is one of the two options at the bottom of the Application Settings page.

Note: If you choose to include both, your application will run exactly as before as web services are called from a different URL.

Web services are only available in supported templates, which include:

Web 2.0 Multiple Record Inquiry (Bootstrap: Multiple Row Data List)
Web 2.0 Single Record Inquiry (Bootstrap: Single Row Data List)
Display and Maintain Rows (Bootstrap: Data List with Web Form)

Once you have selected the desired output, you must then recompile the application. Overwriting is not required to add web services to an existing application.

Note: In order to use web services in a specific data dictionary, a new entry must be made to the web.xml file. m-Power will automatically make this entry, however, the first time a web service is made in a dictionary, you must restart Tomcat in order to use it. This will only need to be done the first time a web service app is created in each data dictionary.

Getting Data

For templates that support data read, use the following URL:
/mrcjava/rest/DD/IXXXXXs/get

…where DD is your data dictionary and IXXXXXs is your app number. Additionally, any parms you would normally pass to the application can also be passed to the webservice like so:
/mrcjava/rest/DD/IXXXXXs/get?parm1=val1&parm2=val2

Note: For a complete list of parms, please see the supporting documentation for each selected template.

Once the URL call is made, a JSON string object will be returned as the response, similar to the screenshot below:

As can be seen, every field value has both the display value (CNAME) and the original value (CNAME_o). The raw data is the same, however the display value has some work done to it such as trimming leading/trailing spaces, numbers formatted according to format codes, etc.

Note: The type and rtndata values can be ignored as they are not used in web services.

CRUD Actions

For templates that support CRUD actions (Create, Read, Update, Delete), use the following URL:
/mrcjava/rest/DD/MXXXXXs/ACTION?key=val&parm1=val1&parm2=val2

…where DD is your data dictionary, MXXXXXs is your app number, and ACTION is the desired action as follows:
Add – post i.e. /mrcjava/rest/DD/MXXXXXs/post?key=val&parm1=val1&parm2=val2
Update – put i.e. /mrcjava/rest/DD/MXXXXXs/put?key=val&parm1=val1&parm2=val2
Delete – delete i.e. /mrcjava/rest/DD/MXXXXXs/delete?key=val

If there were no errors, you will receive a JSON response similar to the following screenshot:

Otherwise, the resulting error will be displayed:

Promoting

You can promote web service applications just like all other applications. The only thing to note is that you will also need to promote the web.xml file the first time you promote a web service per each data dictionary. Once this file has been promoted, Tomcat in production will need to be restarted in order to use the web services for that data dictionary.

Notes

All RESTful web services are stateless. This means that every request is considered completely independent of requests before and after it. Therefore, anything tied to previous requests (notably session and user information) cannot be used unless explicitly passed in your URL request. Some common examples not available in web service applications include row level security, user name references, and session ID references.