Introduction, overview and usage of the Restful Webservice Server
 

The application miscValidatorServer200.exe is a Restful Webservice Server, that has the same interface methods/properties as the COM module miscValidator200.dll. This allows to create a programming semantically similar to the COM approach but under the Restful Webservice paradigm. Consequently, on the Restful Client side there are no prevailing dependencies on Microsoft platforms and/or on Microsoft resources such as the database technology. Of course, the installation location of the server software is still subject to these restrictions.
 
In the next section of this document, the installation, configuration and operation of miscValidatorServer200.exe will be addressed.

Installation, registration and parameterization:
By installing the installer object miscValidator200 the COM module miscValidator200.dll as well as the out-of-process proxy component oopMiscValidator200.exe is automatically installed/registered in the system. However, the miscValidatorServer200.exe must be installed manually as a service.
miscValidatorServer200.exe -help Creates a help window with the the name and full version of the applicationb as well as the currently define Webservice Endpoint. Furthermore the complete list of command line switches is shown.
miscValidatorServer200.exe -install Installs/registers the Restful Webservice Server as a service. Please take into account, that the installation must be performed under administrator privileges
miscValidatorServer200.exe -uninstall Uninstalls the service component. Please take into account, that the uninstallation must be performed under administrator privileges
miscValidatorServer200.exe -setport X Sets the port X as part of the Webservice Endpoint
 
Restful Webservice Endpoint:
Installing miscValidatorServer200.exe as a service activates the Restful Webservice Endpoint:
http://localhost:34558/miscValidatorServer200
which is subsumed as baseURL in subsequent the API documentation.
 
To run the webservice under a different URL or under https protocol, a permanent webservice target endpoint mapping is performed on the target system.
For example, under Apache, the following rewrite rule is defined:
<VirtualHost *:*>
    ProxyPreserveHost Off
	Header always set Access-Control-Allow-Origin "*"
	Header always set Access-Control-Max-Age "1000"
	Header always set Access-Control-Allow-Headers "x-requested-with, Content-Type, origin, authorization, accept, client-security-token"

	ProxyPass /miscValidator/200/ http://localhost:34558/miscValidatorServer200/
	ProxyPassReverse /miscValidator/200/ http://localhost:34558/miscValidatorServer200/
</VirtualHost>		
 
Restful Webservice Operation:
The service may be modified after installation, for example to start under a different account, to extend the recovery properties or to change the startup type. Finally, this should be set to 'Automatic' or 'Automatic (Delayed start)' so that the service is automatically available after a system restart.
 
Remarks about programming:
In the rest of this document we will discuss programming of the Restful web service and the differences to the C/C++ programming of the classic COM component.
 
As already mentioned, Restful programming is analogous to C++ programming with the addition that each instance of an interface (including the main interface) is created via the corresponding GET function. For example, an instance of the main interface is created with:
baseURL/IMiscValidator/GetCreateMiscValidator returns the instance address as JSON out{pIMiscValidator: longValue,...}
In every further call of a method or a property of the main interface this instance address must be included as part of the JSON-In. The termination/deletion of an instance must be done via the corresponding PUT Destruct property:
baseURL/IMiscValidator/PutDestructMiscValidator with JSON-In{pIMiscValidator: longValue}, deletes the corresponding main instance AND all at that moment still active dependent subinstances (subinstances which have been generated by the explicit main instance).
It should be noted that the webserver miscValidatorServer200.exe performs an internal management of the generated instances and automatically deletes instances that have no activity for a defined period of 2 hours. no activity over a defined period of 2 hours. If after this action a rest call with such an instance is made, an error (HTTP Status >= 400) is generated and the instance address is marked as unknown.
 
Code snippet:
Minimal code snippet to query the version of the module and the associated database:
	http://localhost:34558/miscValidatorServer200/IMiscValidator/GetCreateMiscValidator	
		returns JSON-Out{pIMiscValidator: 45467}
		
	http://localhost:34558/miscValidatorServer200/IMiscValidator/GetModuleVersion?pIMiscValidator=45467
		returns JSON-Out{pbstrModuleVersion: "1.00.010"}
		
	http://localhost:34558/miscValidatorServer200/IMiscValidator/GetDBVersionText?pIMiscValidator=45467
		returns JSON-Out{pbstrDBVersionText: "3.22"}
		
	http://localhost:34558/miscValidatorServer200/IMiscValidator/GetDBVersionDate?pIMiscValidator=45467
		returns JSON-Out{pdDBVersionDate: "2021-11-29"}
		
	http://localhost:34778/miscValidatorServer200/IMiscValidator/GetCreateValidate?pIMiscValidator=45467
		returns JSON-Out{pIValidate: 47008}
		
	http://localhost:34778/miscValidatorServer200/IValidate/PutDestructValidate  
		JSON-IN(pIValidate: 47008}
		
	http://localhost:34558/miscValidatorServer200/IMiscValidator/PutDestructMiscValidator   
		JSON-IN{pIMiscValidator:45467}