Differences

This shows you the differences between two versions of the page.

--- groimp-platform:interfaces:api [2024/04/29 15:21] – created gaetan
+++ groimp-platform:interfaces:api [2025/02/10 11:54] (current) – Tim
@@ Line 1: / Line 1: @@
-===== API GroIMP =====
+====== API GroIMP ======
-With the use of the GroLink Project GroIMP can be started as an API server, that can handle Http-requests.
+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.
-==== Get started ====
-Starting with GroIMP 2.1 the API application is included and can be started with the following command:
+The design and implementation is described in more detail [[https://wkurth.grogra.de/oberlaender_msc.pdf|here]].
+===== Key components and their integration =====
-> java -Xverify:none -jar core.jar --headless -a api
+{{ :groimp-platform:interfaces:uml_api.png?direct&600 |}}
-This starts a local web server, the default port is 58081, this can be changed either in the preferences panel in the GUI or by adding ''-Xport=58080'' to the command above.
-A more in-depth explanation of GroIMP arguments can be found [[:user-guide:Advanced-GroIMP-arguments|here]].
+==== Application ====
-Now the API can be reached at [[http://localhost:58081/api|http://localhost:58081/api]]. This will return an error message since no command was given.
+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.
-While the API is running, it is possible to send the commands defined in the [[https://gitlab.com/grogra/groimp-plugins/api|plugin]] directly or by using a client library. For now, there are libraries in [[https://gitlab.com/grogra/groimp-utils/pythonapilibrary|python]]  and [[https://gitlab.com/grogra/groimp-utils/rapilibrary|R]].
+==== 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.
-==== Tutorials ====
+==== Workbench ====
-  * [[:Tutorials:Getting-started-with-GroLink-and-GroPy|getting started with GroLink and Python(GroPy)]]
+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.
-  * [[:Tutorials:Getting-started-with-GroLink-and-GroR|getting started with GroLink and R(GroR)]]
+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.
-  * [[:Tutorials:Getting-started-with-GroLink-and-HTTP|getting started with GroLink and HTTP in your web browser]]
-  * [[:Tutorials:Handeling-data-in-GroLink-Projects|Handling data in GroLink projects]]
-==== Examples ====
+==== Toolkit ====
-  * [[https://gitlab.com/groimp-api-examples/pythonnotebook|Python Notebook]]
-  * [[https://gitlab.com/groimp-api-examples/forester-game|Godot Game]]
+[[https://javadoc.grogra.de/platform/de/grogra/pf/ui/UIToolkit.html|UIToolkits]] in GroIMP are used define how to display panels and other content.
-  * [[https://gitlab.com/groimp-api-examples/apiplus|example Addition]]
+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.