The latest version of KNIME Server 4.3 brings some additions to its REST interface. In this article I will present some of them and how they can be used by client programs. Before we start I should mention that the Mason specification that we are using as the response format has changed slightly and we have adapted KNIME Server accordingly. You may want to have a look at the current version in case you have been using the Mason metadata.
Up and down
The most important addition is the possibility to up- and download items from the workflow repository. The usage is straightforward once you know the addresses. If you read our previous articles on the REST interface ([1], [2]), you may recall that the the workflow repository can be browsed. The entry point for the repository is "/rest/v4/repository/". The meta data of items in the repository can be queried by simply appending the item's path to the base address, e.g. "/rest/v4/repository/workflow", and issuing a GET request. This will return the name, owner, type, as well as some other properties. Note that this also means that the same address cannot be used to access the actual contents of the item. Instead you have to append ":data" to the item's URL and issue a GET request:
. You will also find this address in the @control block of the Mason structure for the particular item (but only if you have permissions to download the item). The result will be a ZIP archive that contains the workflow, data file, or even the whole workflow group. The URL takes an optional query parameter "compressionLevel" with which you can control the compression on the server side (value between 0-9, the default is 1). As any browser can issue a GET request when you paste an URL into the address field, you can easily try this out yourself.
Upload works in the very same way, except that the HTTP method that is used is PUT. The expected request content is also a ZIP archive containing the item to be uploaded. Please note that the request's content type must be "application/zip" otherwise the server will reject it. The ZIP archive is expected to contain exactly one entry at the root level, either the data file or the folder of the workflow or workflow group.
Happy admins
The second change will make all server administrators happy. There are a couple of administration calls that tell you something about the server's current state. All these calls are below "/rest/v4/admin" and - as always - linked in the @control blocks of other resources.
For example you might need to know for how long the server's license is valid and how many users are currently working with the server. In these cases, a GET request to "/rest/v4/admin/license" is your friend:
You see the license type, the number of active users grouped by endpoint (access from KNIME Analytics Platform, from the WebPortal, or web service access), the expiration date, and a few other facts about the license. The list of active users is especially useful in case you reach the limit and additional users are denied access.
Another useful call is "/rest/v4/admin/status". It tells you the server's current configuration, the uptime, and information about the active executors:
In order to use all functionality below "/rest/v4/admin" you must have administration privileges.
Free licences for (almost) everyone
My favourite new functionality in the server is the built-in license server. It serves licenses for extensions such as TeamSpace or Big Data to connected clients. The whole process is perfomed using new REST methods and doesn't rely on the EJB interface any more. The setup is described in the KNIME Server Administration manual and the KNIME Explorer User Guide. We will have a quick look at how it works internally. The corresponding REST endpoint is "/rest/v4/licenses". It shows all available master licenses and also which user is currently using one in his/her local KNIME Analytics Platform installation:
There are also methods for checking out licenses but there is no real use for calling them outside the Analytics Platform itself.
And the REST?
There is still a bit of funtionality missing from the REST interface, such as setting permissions on repository items or scheduling jobs. They will be added in a subsequent release as soon as possible.