The ATL COM module generalInvoiceRequest is capable of
generating electronic and printed invoices & reminders
Introduction, overview and usage of the Restful Webservice Server
 

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

Installation, registration and parameterization:
By installing the installer object generalInvoiceRequestManager450 the COM module generalInvoiceRequestManager450.dll as well as the out-of-process proxy component oopGeneralInvoiceRequestManager450.exe is automatically installed/registered in the system. However, the generalInvoiceRequestManagerServer450.exe must be installed manually as a system service.
generalInvoiceRequestManagerServer450.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.
generalInvoiceRequestManagerServer450.exe -install Installs/registers the Restful Webservice Server as a system service. Please take into account, that the installation must be performed under administrator privileges
generalInvoiceRequestManagerServer450.exe -uninstall Uninstalls the system service component. Please take into account, that the uninstallation must be performed under administrator privileges
generalInvoiceRequestManagerServer450.exe -setport X Sets the port X as part of the Webservice Endpoint
 
Restful Webservice Endpoint:
Installing generalInvoiceRequestManagerServer450.exe as a service activates the Restful Webservice Endpoint:
http://localhost:35340/generalInvoiceRequestManagerServer450
which is subsumed as baseURL in the subsequent 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 /generalInvoiceRequestManager/450/ http://localhost:35340/generalInvoiceRequestManagerServer450/
	ProxyPassReverse /generalInvoiceRequestManager/450/ http://localhost:35340/generalInvoiceRequestManagerServer450/
</VirtualHost>
 
Restful Webservice Operation:
The service might 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/IGeneralInvoiceRequestManager/GetCreateGeneralInvoiceRequestManager returns the instance address as JSON out{pIGeneralInvoiceRequestManager: 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/IGeneralInvoiceRequestManager/PutDestructGeneralInvoiceRequestManager with JSON-In{pIGeneralInvoiceRequestManager: 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 generalInvoiceRequestManagerServer450.exe performs an internal management of the generated instances and automatically deletes instances that have no activity for a defined period of 1 hour. If after the deletion 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 load an XML and produce a PDF representation of that input data: 
		
	http://localhost:35340/generalInvoiceRequestManagerServer450/IGeneralInvoiceRequestManager/GetModuleVersion?pIGeneralInvoiceRequestManager=45467
		returns JSON-Out{pbstrModuleVersion: "1.00.010"}
		
	http://localhost:35340/generalInvoiceRequestManagerServer450/IGeneralInvoiceRequestManager/GetModuleLanguage?pIGeneralInvoiceRequestManager=45467
		returns JSON-Out{peLanguage: "1"}
		
	http://localhost:35340/generalInvoiceRequestManagerServer450/IGeneralInvoiceRequestManager/GetGeneralInvoiceRequest?pIGeneralInvoiceRequestManager=45467
		returns JSON-Out{pIGeneralInvoiceRequest: 5788991}
			
	http://localhost:35340/generalInvoiceRequestManagerServer450/IGeneralInvoiceRequest/PutDestructGeneralInvoiceRequest  
		JSON-IN(pIGeneralInvoiceRequest: 5788991}
		
	http://localhost:35340/generalInvoiceRequestManagerServer450/IGeneralInvoiceRequestManager/PutDestructGeneralInvoiceRequestManager   
		JSON-IN{pIGeneralInvoiceRequestManager:45467}