GroIMP wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
[[https://doi.org/10.21105/joss.08343|{{https://joss.theoj.org/papers/10.21105/joss.08343/status.svg}}]]

====== API ======

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 =====

Starting with GroIMP 2.1 the API application is included and can be started with the following command:

> java -Xverify:none -jar core.jar %%--%%headless -a api

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 [[01_user_documentation:user-guide:advanced-groimp-arguments|here]].

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.


===== HTTP request structure =====

Every command acepted by the API server follows the schema below:

> %%<host>:<port>/api/<ref>/<command>?<key>=<value>%%

  * **host**: The IP of the server (or localhost)
  * **port**: Where the API is listening
  * **ref**: The reference to the workbench (‘app’ or ‘wb/<id>’)
  * **command**: Registry path to the command 
  * **key**: Name of a parameter
  * **value**: Of the parameter

Depending on the command there can be several key value pairs as well as a request body containing decode file. The list of all available commands can be found [[ https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md |here]].

The GroLink API does not distinguish between different request methods. 

===== Project management =====

The GroLink API can be used to manage multiple files and is started without a specific project. To do so a main workbench is used which can be addressed using the reference (ref) "app" in the HTTP request. 
This main workbench can create new workbenches, load provided projects or run embedded examples. 
The main workbench is also able to list all currently opened workbenches. 

In any cases it returns a workbench id that can then be used to address the new workbench with the ref wb/<id>. 
A request send to the sever will be forwarded directly to the referenced workbench, where it is either executed or if the workbench is busy wait. After the completion of the command from the request the request response to the client. In this way the API server has never to wait for any execution to be completed and can run non blocking.

==== Opening a Project ====

There are two different ways to open a project,either the absolute path on the file system is provided and the server can reach this file or the content of the file (this only works with gsz) is decoded and added to the body of the request. The second way has the advantage that it works without a shared file system, for instance on docker, kubernetes or a remote sever. 
   
After transferring the file both commands work similarly, they open a workbench the same way as in the GUI or the CLI and then return a workbench ID.
([[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#open-project | command description]])

==== Creating a workbench ====

[[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#create-new-workbench | Creating a new workbench]] will end in the same result as clicking file > new in the GUI. 
By default the new workbench will be using the new RGG template, yet it is possible to provide the name of another template that should be used. The templates can be listed with a [[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#list-templates | specific command]].
 

==== Loading an example ====

[[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#list-examples |Listing]] and [[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#load-example |loading examples]] works similar to creating a workbench. 


==== Saving a project ====

Saving the project is a workbench command that has to be addressed to the workbench that is suppose to be saved. If a path is provided the project will be saved at that location, otherwise if no path is provided the decoded gsz file will be returned to the client. This allows to save project that where executed on other file systems. 
([[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#save-the-project | command description]])

===== Project interaction =====
 

==== RGG/ XL ====

It is possible to send the name of an RGG function to the project and receive the output of the XL console as a result ([[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#run-rgg-function |command]]). Additionally it is possible to [[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#list-rgg-functions | list all RGG functions]].

In a similar fashion it is possible to [[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#run-xl-queryrules | run XL queries]], which are then executed in a environment similar to the XL-Console. Only with the limitation that in contrast to the console it is not possible to save variables between two calls. 
While it is possible to send the XL query as an URL parameter, for more complex queries it would be recommended to use the request body since several characters of the XL syntax are effecting urls.

==== Graph view ====

The API can [[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#get-project-graph |provide JSON based representation of the project Graph]].

The JSON format uses two dictionaries to represent the graph: "projectgraphNodes" and "projectgraphEdges".
The projectgraphNodes list holds the nodes themselves with their node id. This ID is again used in
triples of the projectgraphEdges list to define the source (first entry) and the destination (second entry). The third value in the triple represents the edge bits to seperate for example successor and branch. Finally the projectgraphRoot represents the root node of the project graph.
 

==== File management ====

The source files of a project can be [[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#list-source-files |listed]], [[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#get-source-file-content | read]], [[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#remove-source-file | removed]],[[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#add-source-file| added]] or [[ https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#update-source-file | updated]]. 

Adding a file can be done via a path or as a request body, similar to opening a project. 
Updating a file will replace the content of the given file with the body of the request, meaning to change only one line it would be reasonable to first read the file, change it locally and then send it back.
   

==== Import/Export ====

[[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#add-external-file-to-scene | Importing]] and [[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#export-the-scene |exporting]] can both be done either via path or within the request/response. For the second case the extension is required as an argument.

==== Data handling ====

While data handling through external files for instance for logging, is still possible, this would not be that suitable for a setup where the API server and the client are not running on the same system.
In that case a possible way is to just add input data files as source files to the project and read them from RGG. 

To receive data from the simulation one possible way is to use datasets, the API has specific commands to [[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#list-existing-datasets|list]] and [[https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md#get-the-content-of-a-dataset|read]] datasets.  


===== Client libraries =====

Due to the generalized approach using registry paths, the HTTP commands are quite long and complex. 
To ease this and the management of the workbenches, client libraries are provided in R and Python.
==== GroPy ====

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 ===

The library is based on three classes: Call, GroLink and WBRef. 

== Call ==

A call object represents a possible request to the API server and can be send with the run function and the results can be interpreted with the read function. The run function returns the object itself to enable a short writing form: ''myCall.run().read()''. The read function can return either a file, a json-String or a WBRef object, depending on the command.

== 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 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 provides function to create calls for the [[#project_interaction |Project Interaction]].([[https://gitlab.com/grogra/groimp-utils/pythonapilibrary#wbref|List of Python commands]])

=== 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]]

=== 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)]]
  * [[01_user_documentation:groimp-platform:interfaces:api|API implementation]]

===== Tutorials =====

  * [[02_user_tutorials:07_additional_interfaces:api:03_getting-started-with-grolink-and-gropy|getting started with GroLink and Python(GroPy)]]
  * [[02_user_tutorials:07_additional_interfaces:api:04_getting-started-with-grolink-and-gror|getting started with GroLink and R(GroR)]]
  * [[02_user_tutorials:07_additional_interfaces:api:02_getting-started-with-grolink-and-http|getting started with GroLink and HTTP in your web browser]]
  * [[02_user_tutorials:07_additional_interfaces:api:05_handeling-data-in-grolink-projects|Handling data in GroLink projects]]
  * [[02_user_tutorials:07_additional_interfaces:api:07_grolink-on-kubernetes|Deploying GroIMP/GroLink on Kubernetes]]
  * [[05_developer_tutorials:02_extending_groimp: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]]
  * [[https://gitlab.com/groimp-api-examples/apiplus|example Addition]]