Using Web Services

Click here to access legacy documentation for this feature

Introduction

Modern web applications often use APIs to send and retrieve data. m-Power has the capability to create APIs using RESTful web services now available via a dedicated maintainer template. With this template a web service can be built to retrieve data from as well as write data to a database. For more information regarding REST, please see this link.

Authentication Types

m-Power supports three distinct authentication types to secure your web services: Bearer Tokens, API Keys, and Basic Authentication. If security is enabled in your dictionary you will need to select a desired mechanism to authenticate your web service from Admin -> Menu & Security -> Edit Security Settings:

If dictionary security is disabled, authentication is not required.

Bearer Tokens

The client application will need to post a user/password HTTP POST request to the Login endpoint to obtain the token value. When the Login endpoint is called, the credentials included in the request are checked against the validation type configured in the Security Setting here:

If the user is valid, a token and token expiration time are stored in the MRCSEC1 fields: TOKEN and EXPIRES. On each subsequent request the token is sent with the request for validation and the the expiration time is updated so the user does not have to sign back in.

This user will need to be created as an Application User to be stored in MRCSEC1 to associate the generated bearer token to the appropriate user.

Login endpoint is [SERVER_IP:PORT]/mrcjava/rest/[DICTIONARY]/Login. Make a POST request with the login payload, where “myuser” is the username and “mypassword” is the user password:

A Successful response contains a token. The client application will send this token as an authorization bearer token with each request to the web service.

A Failed response might look like this:

The authentication token should be sent with each request as a bearer token. That means the token should be sent as a name/value HTTP header called “Authorization” and the value prefixed with the word “Bearer” like this:

Authorization: Bearer UT8rsJYsgtxwgJfaZ_eLm6c14cR-k0-0

“Authorization” is the name of the header.

“Bearer UT8rsJYsgtxwgJfaZ_eLm6c14cR-k0-0” is the value.

API Keys

For some types of apps/web services that require less security, API keys are an easier way to manage user authentication. In the interface on the Update Application User screen, click the “Generate API Key” button to issue an API key for a user which is stored in MRCSEC1.

Upon saving the user info, this popup will appear urging the developer to save the API key somewhere as it is not able to retrieved again. It is not able to be retrieved again because the template uses one-way hash encryption when storing it in the database. This means that once it is stored with the hash it is not able to be decrypted by anyone, including mrc. If needed, developers can simply re-generate the API key for any given user.

The API key should be sent with each request as a bearer token. That means the token should be sent as a name/value HTTP header called “Authorization” and the value prefixed with the word “Bearer” like this:

Authorization: Bearer VM2BGT6-C0XM36Y-KXCK5FR-ZXWF3HR

“Authorization” is the name of the header.

“Bearer 0XM36Y-KXCK5FR-ZXWF3HR” is the value.

Basic Authentication

Basic authentication is an authentication scheme built into the HTTP protocol that also uses the Authorization header (similar to the above options). The difference is that the Basic Authentication sends the username and password in the header value prefixed by the word “Basic” such as “Authorization: Basic myuser:mypassword”. The user and password are base64 encrypted.

m-Power provides two options for using basic authentication:

1. You can request a Bearer or JSON web token using basic authentication by making a GET request to the /[DICTIONARY]/Login endpoint and passing the basic authorization header to it with username/password as outlined in the previous paragraph. This returns a bearer token that can then be sent in requests to actual web services.
2. If desired, you can also pass the basic authentication header with EVERY request to the web services endpoint in lieu of the bearer token. This is considered less secure but is still sometimes needed.

There is no additional configuration needed to use basic authentication. When requesting a bearer token via the Login endpoint, m-Power will detect that the basic authorization header has been sent with the request and will use that instead of trying to process a posted JSON body with username/password. Also, if no bearer token is sent to the web service, m-Power will check for the basic authorization header and perform the user validation with each request.

Making API Calls

The base URL to make a Web Service call is /mrcjava/rest/[DICTIONARY]/MXXXXXs.
i.e. /mrcjava/rest/MRCWORKLIB/M00010s.

GET Data

To get data from the service, call it using a GET request. You may pass additional parameters via the URL to filter the data:

[FIELD]: Pass a field name and desired value as parameters to filter the data with an equal to relationship.
i.e. /mrcjava/rest/MRCWORKLIB/M00010s?PNUM=1540.

rls_[FIELD]: In addition to the above [FIELD] parameter, you can change the default relationship when filtering data such as LE (Less than), GE (Greater than or equal to), RG (Range), etc.
i.e. /mrcjava/rest/MRCWORKLIB/M00010s?rls_PCLASS=LS&PCLASS=B%20C.

A successful response is returned in a JSON string object, similar to the screenshot below:

As can be seen, every field value has both the display value (PCLASS) and the original value (PCLASS_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.

Any errors from the application will be returned similar to the screenshot below:

POST Actions

To add/update/delete records, call it using a POST request. You must pass the appropriate action via a URL parameter:
Add: /mrcjava/rest/DICTIONARY/MXXXXXs?action=add
Update: /mrcjava/rest/DICTIONARY/MXXXXXs?action=update
Delete: /mrcjava/rest/DICTIONARY/MXXXXXs?action=delete

Additionally, send the appropriate data/parameters as a JSON payload:

A successful response will look like the following:

A failed response might look like this:

Troubleshooting Notes

• New dictionaries created after the May 2021 update will automatically have Web Services configured. To configure web services in existing dictionaries, open the mrcSignon2.xml properties file (Admin menu -> Menu & Security -> Edit Security Settings -> Property Options -> Text Mode) and immediately above the tag, add the following:

  <webserviceValidationType pdesc="webserviceValidationType" value="1" />

  After saving, the authentication options will appear in the GUI security settings as stated above.

• During the Apply Update process, m-power will attempt to alter MRCSEC1 and add two new columns (TOKEN and EXPIRES). If you need to do this manually or if you have a separate production database, use these alter statements (replacing [DICTIONARY] with the name of your dictionary):
  • ALTER TABLE [DICTIONARY].MRCSEC1 ADD TOKEN VARCHAR(5000);
    ALTER TABLE [DICTIONARY].MRCSEC1 ADD EXPIRES DATETIME;
  • Note: Replace DATETIME with the appropriate timestamp column type for the database.

• 404 Error: During the compile of the Web Services template, m-Power should automatically add the dictionary name and ‘mrc’ to the /mrcjava/WEB-INF/web.xml file. If your API call returns a 404 error, confirm the dictionary name and ‘mrc’ has been added to the mrc-REST-Service param-value list in /mrcjava/WEB-INF/web.xml: