With the use of the GroLink Project GroIMP can be started as an API server, that can handle Http-requests.
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 here.
Now the API can be reached at http://localhost:58081/api. This will return an error message since no command was given.
Every command acepted by the API server follows the schema below:
<host>:<port>/api/<ref>/<command>?<key>=<value>
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 here.
The GroLink API does not distinguish between different request methods.
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.
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. ( command description)
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 specific command.
Listing and loading examples works similar to creating a workbench.
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. ( command description)
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 (command). Additionally it is possible to 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.
The API can 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.
The source files of a project can be listed, read, removed, added or 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.
Importing and exporting can both be done either via path or within the erquest/response. For the second case the extension is required as an argument.