====== API GroIMP ======

The [[user-guide:additional_interfaces:api|GroLink]] PI in GroIMP is implemented as a new "GroIMP application" including a toolkit, workbenches, and a workbench manager. 


The design and implementation is described in more detail [[https://wkurth.grogra.de/oberlaender_msc.pdf|here]].
===== Key components and their integration =====

{{ :groimp-platform:interfaces:uml_api.png?direct&600 |}}


==== Application ====

The [[https://javadoc.grogra.de/api/de/grogra/api/APIApplication.html| APIApplication]] is the class that is executed during the boot process of GroIMP if the parameter "-a api" is used. It extends the class [[https://javadoc.grogra.de/platform/de/grogra/pf/ui/UIApplication.html| UIApplication]] and initialized the workbench manager and the toolkit before starting the API Server.

==== Workbench manager ====

The [[https://javadoc.grogra.de/platform/de/grogra/pf/ui/WorkbenchManager.html |APIWorkbenchManager]] is required to resolve each workbench to its unique id to allow parallel interaction with projects.

==== Workbench ====

Each UIApplication in GroIMP has it's own workbench (GUI,CLI,API), this is necessary because even so they implement the same commands, the interpretation of the input is different. 
The generalized workflow of this is that the registry command is calling a static function in [[https://javadoc.grogra.de/platform/de/grogra/pf/ui/ProjectWorkbench.html |ProjectWorkbench]], which resolves the current workbench form the context and forwards the (at this state quite vague) variable info to a function in the application specific workbench which interprets the content of info and calls the version of the function that takes proper defined parameters, which is often defined in ProjectWorkbench.


==== Toolkit ====

[[https://javadoc.grogra.de/platform/de/grogra/pf/ui/UIToolkit.html|UIToolkits]] in GroIMP are used define how to display panels and other content. 
The APIToolkit is quite small since only the content of the XL console is returned to the client. In a future version this could be extended by creating a json based toolkit which would allow the access to all information of a workbench in a simpler way.

==== Server ====

The APIServer extends the abstract class [[https://javadoc.grogra.de/utilities/de/grogra/http/Server.html server]]. It simply takes any request that starts with /api and initializes a new APIRunner with the content.


==== Runner ====

The [[https://javadoc.grogra.de/api/de/grogra/api/APIRunner.html|APIRunner]] implements [[https://javadoc.grogra.de/platform/de/grogra/pf/ui/Command.html| Command]] which enables the class to be pushed to the job manager of the different workbenches. 
The runner resolves the workbenches and commands defined in the requests and is the core component of the [[#call_lifecycle |call lifecycle]].  

Additionally each instance of a runner holds a APIReturn object to manage the information that are suppose to be send back to the user. 

====  Return ====

The [[https://javadoc.grogra.de/api/de/grogra/api/APIReturn.html |APIReturn]] class is basically a JSON wrapper. 


===== Call lifecycle =====

{{:groimp-platform:interfaces:api_call_lifecycle.png?direct&600|}}

Each API call send out by a client is first handled by the API/HTTP server. The server creates for each request a new instance of API Runner with the request and the client address as a parameter. During the instantiation the API Runner instance decodes the parameters, and resolves the command based on the registry and the workbench based on the workbench manager. Afterwards the APIRunner adds it self to the queue of the job manager of the resolved workbench. 

When then executed by the job manager, it executes the resolved command with it self as the info parameter. 
This allows the executed command to access the provided parameters from the http request and allows to add new information to the APIResponse.

After the execution of the resolved command, the APIRunner instance collects some additional information form the workbench (the logs and the content of the xl-console) and wraps this with the data added by the command. It then sends the result back  to the client.