Differences

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

--- user-guide:additional_interfaces:api [2025/01/22 12:23] – [GroPy] Tim
+++ user-guide:additional_interfaces:api [2025/02/07 17:12] (current) – [Examples] Tim
@@ Line 1: / Line 1: @@
-====== API GroIMP user guide ======
+====== API ======
-With the use of the GroLink Project GroIMP can be started as an API server, that can handle Http-requests.
+GroIMP can be started as an HTTP API that provides a generalized set of commands allowing interaction from other software. Currently a Python and a R library are provided but any software capable of HTTP requests could interact with GroIMP. This approach can be used to automatically start a simulation and interact with it during the execution.
+<uml>
+@startuml
+!pragma teoz true
+hide footbox
+title API
+participant User
+participant ClientScript
+participant API
+participant GroIMP
+User -> GroIMP: Start GroIMP
+User -> ClientScript
+ClientScript <->API
+& API<-> GroIMP
+User <- ClientScript
+User -> GroIMP: Stop GroIMP
+@enduml
+</uml>
 ===== Installation and execution =====
@@ Line 109: / Line 132: @@
 ==== GroPy ====
-The [[https://gitlab.com/grogra/groimp-utils/pythonapilibrary|GroPy]] library provides an object orientated Python3 implementation.
+The [[https://gitlab.com/grogra/groimp-utils/pythonapilibrary|GroPy]] library provides an object orientated Python3 implementation. It can be installed using the pip installer using the package registered at the repository:
+<code bash>
+pip install GroPy --index-url https://gitlab.com/api/v4/projects/50527255/packages/pypi/simple
+</code>
+Additionally it is possible to only get the file GroPy.py from the repository and link it directly.
 === Structure ===
@@ Line 121: / Line 148: @@
 == GroLink ==
-The GroLink class holds the connection to the API server and can create different calls for [[#project_management | Project Management]] (e.g. create or open new workbenches), most of these commands return WBRef objects ([[https://gitlab.com/grogra/groimp-utils/pythonapilibrary#grolink|List of commands]]). It is initialized with the address to the API server.
+The GroLink class holds the connection to the API server and can create different calls for [[#project_management | Project Management]] (e.g. create or open new workbenches), most of these commands return WBRef objects ([[https://gitlab.com/grogra/groimp-utils/pythonapilibrary#grolink|List of Python commands]]). It is initialized with the address to the API server.
 == WBRef ==
-A WBRef object represents the connection to a workbench, it does not hold any information other than the id of the workbench and the link to the API server. This object can than be used to address the
+A WBRef object represents the connection to a workbench, it does not hold any information other than the id of the workbench and the link to the API server. This object provides function to create calls for the [[#project_interaction |Project Interaction]].([[https://gitlab.com/grogra/groimp-utils/pythonapilibrary#wbref|List of Python commands]])
-=== Project management ===
-=== Project interaction ===
 === custom calls ===
+Due to the design of the API server it is possible to send request regarding commands that where not originally part of the GroLink project. To be able to address this command from the python library the function '' createAppCall(self, command, returnType=Call.JSON_RETURN, parameters=None, content=None)'' or ''createWBCall(self, command, returnType=Call.JSON_RETURN, parameters=None, content=None)'' can be used.
+<code python>
+link = GroPy.GroLink("http://localhost:58081/api/")
+link.createAppCall("/path/to/the/command")
+WBref1 = link.createWB().run().read()
+WBref1.createWBCall("/path/to/the/command")
+</code>
 ==== GroR ====
 [[https://gitlab.com/grogra/groimp-utils/rapilibrary|R]]
-===== Tutorials and examples =====
+=== Installation ===
+The GroR package is not added to any public repository and must therefore be installed by hand. This can be done in different ways depending on your needs.
+== Adding the R file as a Source ==
+It is possible to download the GroR.R file from this repository and link it to your R file with this code:
+''source("path/to/GroR.R")''
+== Package ==
+The releases contain packages that can be installed directly with either the R command:
+''install.packages("path/to/GroR_x.x.x.tar.gz", repos = NULL, type = "source")''
+Alternatively, it is possible to install the package with the R Studio package manager by selecting “install from package archive file”.
+=== Structure ===
+The library comes with two sets for functions, one set with the prefix "GroLink." and one with the prefix "WBRef.". The GroLink.* functions take the address of the API server as first input and provided a implementation for most [[#project_management | Project Management]] requests. Most of them return wb objects which are the first needed parameter for the WBRef.* functions. These functions implement the requests for [[#project_interaction | Project interaction]]. A list of all avialable commands can be found in the [[https://gitlab.com/grogra/groimp-utils/rapilibrary/-/blob/main/README.md|readme]] of the repository.
+===== More documentation =====
+  * [[https://wkurth.grogra.de/oberlaender_msc.pdf| GroLink: implementing and testing a general application programming interface for the plant-modelling platform GroIMP (original Thesis)]]
+  * [[:groimp-platform:interfaces:api|API implementation]]
 ===== Tutorials =====
+  * [[:Tutorials:Startup-API |Start the API]]
   * [[:Tutorials:Getting-started-with-GroLink-and-GroPy|getting started with GroLink and Python(GroPy)]]
   * [[:Tutorials:Getting-started-with-GroLink-and-GroR|getting started with GroLink and R(GroR)]]
   * [[: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]]
+  * [[:Tutorials:grolink-on-kubernetes|Deploying GroIMP/GroLink on Kubernetes]]
+  * [[:dev-guide:create-new-api-function|How to create new API commands]]
 ===== Examples =====
-  * [[https://gitlab.com/groimp-api-examples/pythonnotebook|Python Notebook]]
-  * [[https://gitlab.com/groimp-api-examples/forester-game|Godot Game]]
+We provide examples in Python, R and Godot to get a first impression: https://gitlab.com/groimp-api-examples.
-  * [[https://gitlab.com/groimp-api-examples/apiplus|example Addition]]
+Additionally you can find there a ready to use docker container to ease the first tests.