m-Power Web Services
Click here to access legacy documentation for this feature
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.
The client application posts a user/password as JSON to the Login endpoint. This performs a standard table validation lookup in MRCSEC1 to determine if it's a valid user. If it is a valid user, a token and token expiration time are stored in new 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.
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 and store it 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 client application will send this API key as a bearer token with each request to a web service.
Basic authentication is an authentication scheme built into the HTTP protocol that also uses the Authorization header (similar to the bearer token). 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:
- 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.
- 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.
Note 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.
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.
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.
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.
To add/update/delete records, call it using a POST request. You must pass the appropriate action via a URL parameter:
- 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:
- 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: