Introduction, overview and usage of the Restful Webservice Server
 

The application tarmedValidatorServer100.exe is a Restful Webservice Server, that has the same interface methods/properties as the COM module tarmedValidator100.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 tarmedValidatorServer100.exe will be addressed.

Installation, registration and parameterization:
By installing the installer object tarmedValidator100 the COM module tarmedValidator100.dll as well as the out-of-process proxy component oopTarmedValidator100.exe is automatically installed/registered in the system. However, the tarmedValidatorServer100.exe must be installed manually as a service.
tarmedValidatorServer100.exe -help Creates a help window with the the name and full version of the application as well as the currently define Webservice Endpoint. Furthermore the complete list of command line switches is shown.
tarmedValidatorServer100.exe -install Installs/registers the Restful Webservice Server as a service. Please take into account, that the installation must be performed under administrator privileges
tarmedValidatorServer100.exe -uninstall Uninstalls the service component. Please take into account, that the uninstallation must be performed under administrator privileges
tarmedValidatorServer100.exe -setport X Sets the port X as part of the Webservice Endpoint
 
Restful Webservice Endpoint:
Installing tarmedValidatorServer100.exe as a service activates the Restful Webservice Endpoint:
http://localhost:34118/tarmedValidatorServer100
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 /tarmedValidator/100/ http://localhost:34118/tarmedValidatorServer100/
	ProxyPassReverse /tarmedValidator/100/ http://localhost:34118/tarmedValidatorServer100/
</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/ITarmedValidator/GetCreateTarmedValidator returns the instance address as JSON out{pITarmedValidator: 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/ITarmedValidator/PutDestructTarmedValidator with JSON-In{pITarmedValidator: 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 tarmedValidatorServer100.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:34118/tarmedValidatorServer100/ITarmedValidator/GetCreateTarmedValidator	
		returns JSON-Out{pITarmedValidator: 45467}
		
	http://localhost:34118/tarmedValidatorServer100/ITarmedValidator/GetModuleVersion?pITarmedValidator=45467
		returns JSON-Out{pbstrModuleVersion: "1.00.010"}
		
	http://localhost:34118/tarmedValidatorServer100/ITarmedValidator/GetDBVersionText?pITarmedValidator=45467
		returns JSON-Out{pbstrDBVersionText: "3.22"}
		
	http://localhost:34118/tarmedValidatorServer100/ITarmedValidator/GetDBVersionDate?pITarmedValidator=45467
		returns JSON-Out{pdDBVersionDate: "2021-11-29"}
		
	http://localhost:34118/tarmedValidatorServer100/ITarmedValidator/GetCreateValidate?pITarmedValidator=45467
		returns JSON-Out{pIValidate: 47008}
		
	http://localhost:34118/tarmedValidatorServer100/IValidate/PutDestructValidate  
		JSON-IN{pIValidate:47008}
		
	http://localhost:34118/tarmedValidatorServer100/ITarmedValidator/PutDestructTarmedValidator 
		JSON-IN{pITarmedValidator:45467}