Skip to content

MVsharp REST API

Details and examples of using MVrest to integrate into the MVsharp environment.

Contents

1 Introduction

2 Pre Requisites

3 MVSHARP REST Files

4 Creating REST services

4.1 Creating Classes

4.2 Creating REST Methods

4.3 Deploying REST Application

5 Managing the REST interface

5.1 Starting the Server

5.2 Stopping the Server

5.3 Resetting the connections on the Server

5.4 Getting the Connection Status

Introduction

The MVrest is architected differently from the MVSHARP REST API. Where the REST API is a more generic REST interface that allows you to call subroutines, the output cannot be tailored to suite complex object type. The MVrest allows you full control to return complex data structures from a REST call.

Another important difference between the two API's is the deployment mechanism. The REST API relies on being deployed on an IIS server, this limits the ability to have your REST server only on a Windows platform with IIS installed. The configuration and management of IIS can be complex at times.

The MVrest is deployed on dotnetcore 3.1 with an internally hosted HTTP pipeline. This means no configuration of a web server is required as the entire REST server is hosted in the application.

Another important design feature of the MVrest is to generate a complete dotnetcore 3.1 project with full source so that modifications can be made when specific requirements are not met by the generic REST interface. It is important to note that if you modify the source code, when you redeploy the services, all changes will be lost.

Pre Requisites

Before using the MVSHARP MVrest, the following needs to be in place:

  1. Microsoft dotnetcore 3.1 is installed on the server.

  2. MVsharp 4.0.81 or later is installed.

  3. MVrest Administrator 4.0.1 or later is installed.

MVSHARP REST Files

MVrest stores the configuration information required to deploy the REST Services in the account you are connecting to. This ensures that the configurations can be backup up and restored to new locations.

Each account can have its own set of services that can be deployed using a different port.

The first time you connect to an account to configure Web Services, you will be prompted to "Create Web Services Files". The following files are created in the selected account

File Name Description
MvClasses This file contains all the definitions of the classes configured to support the input and output to and from the REST Services Each class name must be unique and may be used for multiple methods.
MvRestServices This file contains the Method definitions and input and output mappings for each REST Service.

Creating REST Services

Creating a REST Service normally consists of the following steps:

  1. Create a set of classes that map to properties to specific attributes in a dynamic array. A class may contain sub classes in order to generate a complex structure in the result.

  2. Create a subroutine definition that defines the input and output parameters of the REST service. Each output parameter can be mapped to a class that will return the data received from the subroutine parameters when called.

In order to demonstrate the processes involved in exposing REST Services in MVSHARP, we are going use a sample database and some sample subroutines to show the configuration process.

The demonstration database contains a file called "INVOICES":

Field Name Position Description
InvoiceNumber 0 The key to the CUSTOMER File (Numeric)
CustomerName 1 Customer Name (Alpha Numeric)
Address 2 Multi Valued List of Addresses (Alpha Numeric)
ProductNo 3 Multi Valued List of product numbers
Quantity 4 Multi Valued list of quantities
Price 5 Multi Valued list of prices
OrderTotal 6 Total of the order

The above structure is used to show how to define:

  1. Address is multivalued but not associated to any other fields
  2. CustomerName and OrderTotal are single valued fields not associated to other fields
  3. ProductNo, Quantity and Price are multivalued and all associated with each other.

When translating a multivalued record as above into a class structure, we will need a separate class for each of the associated multi valued fields. In the above example we will have 2 classes

  1. Invoice - containing, CustomerName, Address and OrderTotal
  2. Invoice_Detail - containing ProductNo, Quantity and Price.

Creating Classes

Classes are created using the MVSHARP Changeover administrator. Open the ChangeOver Administrator and select the "Web Services" tab. As mentioned in the introduction, each account has its own definitions for classes and services. Select the "Source System" and "Source Account" where the REST services are going to be created.

rest_sub_pic_1

Refer to MVsharp Administrator manual for details on how to define server connections to the various databases.

  • Select the "Source System" and "Source Account" from the drop downs provided.

  • The first time you access the Web Services tab for an account you will be prompted to create the required files.

  • We first need to create all the associated multivalued classes. This is because the collection editor allows us to select the "ClassName" described above from a dropdown list.

  • Enter the class name "Invoice" in the input box next to "Add Class" and press the "Add Class" button. Repeat the process for "Invoice_Detail

  • Expand the "Class Definitions" tree item and click on "Invoice".

  • Click on the "(Collection)" button in the Properties Window.

rest_sub_pic_1

As described above, the Invoice class has 3 properties and 1 class. Click the "Add" button in the Collection editor 4 times to create 4 new properties for this class.

Each property can be configured with the following properties:

Note: ArrayLength and IsArray properties are deprecated and are only there for backwards compatability.

Property Name Description
ClassName The name of an internal class that contains properties. This is used when we have associated multivalues.
DataType REST Subroutines only uses the string datatype. MV platforms have no data typing.
IsList Set to true when we have a multivalue that is not associated with and other value.
Location The attribute no that will be populated from an output argument.
Name The name of the property.

For the first 3, properties set the name to (CustomerName, Address and OrderTotal) and the Location to (1, 2 and 6). For the Address property, set "IsList" to true as it is a multivalue.

The 4th property we are going to define a class that has all out associates multivalued fields. (ProductNo, Quantity and Price).

rest_sub_pic_1

Note the following when specifying an inner class:

  • Select the class name from the dropdown list.
  • The IsList property should be true if the association is multivalued.
  • The location must set to the controlling multivalue field.

Repeat the above process for "Invoice_Detail" class with properties ProctNo,Quatity and Prices with Location set to 3,4 and 5.

rest_sub_pic_1

Note the following when specifying the class:

  • The "IsList" property is set to false even though the data is multivalued.
  • The "IsList" property of the controlling class was set to true, making the entire class multivalued.

The classes are now complete, you can save each class by clicking on the class in the TreeList and then Right Clicking the name and selecting save.

rest_sub_pic_1

Creating REST Methods

Methods are created using "REST Web Services" tab located at the bottom of the screen. After selecting the tab and clicking on the REST Web Services tree item the following properties are displayed. These properties are defaulted from you current source connection.

rest_sub_pic_1

Property Name Description
AccountName The account name that contains the data and subroutines.
ConnectionTimeout The amount of seconds to wait for a connection before timing out.
DeploymentPath The path locally where the dotnetcore project will be deployed.
IdleTimeout The no of seconds a connection will stay connected without processing a message. The connection is closed after this period.
LoginId The login id of the user to connect to the MVSHARP Server.
MVSHARPServer The hostname or IP address of the MVSHARP server.
Password The password associated with the login id above.
PoolMaxSize The maximum no of concurrent connections allowed to MVSHARP.
PoolMinSize The no of connections to start up when the server is started.
Route The REST route for each subroutine call.
HttpPort The port no of HTTP traffic, if set to 0, HTTP traffic is disabled.
SSLPort The port no of SSL traffic, if set to 0, SSL traffic is disabled.

You can save any configuration changes by clicking on the "Save" button at the top of the Object Properties.

To create a new subroutine call, enter the subroutine name in the text box next to the "Add REST Subroutine" button and the click the "Add REST Subroutine" button.

For our example the subroutine has 3 arguments, the "InvoiceNo, "Status" and "InvoiceDetail" variable. The 1st argument is an input parameter and the 2nd is an output parameter.

E.g. GetInvoice(InvoiceNo,Status,InvoiceDetail)

Click on the "Parameters" button in the Object Explorer and add 3 Parameters.

rest_sub_pic_1

Each parameter can have the following properties:

Property Name Description
ClassName If the parametertype is Output and the parameter updates a class, you can select the classname from a list.
Name The name of the parameter.
Order The order in which the subroutine arguments are set.
ParameterType Either Input or Output depending if the value is passed to the subroutine or the value is used to format the JSON document
Type Either String, Json or dynamicarray.

For out example set the following:

  • Parameter1 Name is InvoiceNo, Order is 1 and ParameterType is Input and Type is String

  • Parameter2 Name is Status, Order is 2 and ParameterType is Output and Type is String

  • Parameter3 ClassName is Invoice, Name is Invoice, ParameterType is Output and Type is String

rest_sub_pic_1

You save the definition by clicking on the subroutine in the Treeview, right clicking and selecting Save Test program for this example

    Subroutine GetInvoice(InvoiceNo,Status,InvoiceRec)
*-----
*   demo subroutine to test the MVSHARP REST subroutine API
*   if the InvoiceFile does not exist is it created and populated
*-----
    Open "InvoiceFile" To InvoiceFile Else Execute "Create.File InvoiceFile"
        Open "InvoiceFile" To InvoiceFile Else Return
        Rec1 = "Customer1,addr line1|addr2|addr3,prod1|prod2|prod3,10|5|22,11.99|88.98|67.12,1099.66"
        Rec2 = "Mr Joe Bloggs,370 Rivonia Blvd|Rivonia|Sandton,123-001|01x-321|667-123,1|2|3,1.99|8.77|12.55,27.44"
        Convert "," To @Am in Rec1
        Convert "|" To @Vm in Rec1
        Convert "," To @Am in Rec2
        Convert "|" To @Vm in Rec2
        Write Rec1 On InvoiceFile , 1000
        Write Rec2 On InvoiceFile , 1001
    End
    Status = "Record Not Found - ":InvoiceNo
    Read InvoiceRec From InvoiceFile , InvoiceNo Then 
        Status = "Ok"
    End
    Return

Deploying REST Application

A complete dotnetcore project is created during deployment that can be loaded into VSCODE or Visual Studio. All the source code for the REST server is in the project. The project can be debugged by loading the project into VSCODE or visual studio and running the project in debug mode.

To deploy the project, right click in the REST web services tab and select Publish.

rest_sub_pic_1

You project will be deployed into the path specified in the DeploymentPath parameter described in 4.2.

Once the project is deployed it will be compiled and the compilation results will be displayed. If the compilation fails, there is an incorrect configuration.

Managing the REST Interface

Starting the Server

For testing purposes you can start the REST server from the Changeover Administrator. On the REST Web Services tab, select "Start the REST Server". This will start the server on your local machine.

Stopping the Server

There are some default GET REST calls to manage the REST server. Submitting the following HTTP GET call will stop the REST server. This can be done from a REST client or in a Browser.

http://localhost:{port}/api/stop

Resetting the Connections on the Server

If there are connections to the MVSHARP that are not processing, all connections can be reset without restarting the REST server with the following URL

http://localhost:{port}/api/reset

Getting the Connection Status

To check the number of connections and the status of each connection the following URL

http://localhost:{port}/api/status

•   [
•       {
•           "connection": "Thread 1",
•           "lastProcessed": "2020-04-08T16:34:20.1146296+02:00",
•           "messagesProcessed": 1,
•           "isProcessing\": false
•       }
•   ]

Copyright © 2018 Prosol Group

All rights reserved.

Prosol Group make no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Prosol Group or an authorised sub licensor.

Neither Prosol Group nor its employees are responsible for any errors that may appear in this publication. The information in this publication is subject to change without notice.

All other trademarks and service marks are property of their respective holders.