[Draft] Unimus API v3 - feedback wanted

Beta release announcements and discussion around them
Post Reply
User avatar
Posts: 1238
Joined: Sat Jun 25, 2016 12:33 pm

Wed Aug 11, 2021 11:06 pm

Hi everyone,

We are currently in the final stages of design for Unimus API v3, and we would love your feedback on the proposed design. The current API v2 available in Unimus has been a bit ... neglected - as new features were added to Unimus, the API has not been kept up to date. As such, things like Zones, Credentials management and Config Push are not available in the current v2 API.

With the API v3, we want to solve all of these missing pieces. The API should also be a bit easier to use than the current v2 API. Before we start implementing, we would love feedback on what you think about the new API endpoint format, data representation, etc.

You can browse the docs for the new API here: https://download.unimus.net/api-v3-preview/

Any comments, feedback and/or questions are very welcome!
Posts: 23
Joined: Tue Aug 11, 2020 12:08 pm

Mon Sep 13, 2021 7:08 am


No comments with regards to design etc, but I wanted to emphasise that this a game-changing for our implementation. All the new API features will mean that we can fully automate zone designation, credentials etc. for new devices. So this development is greatly appreciated!
User avatar
Posts: 1238
Joined: Sat Jun 25, 2016 12:33 pm

Fri Dec 17, 2021 9:56 pm

Just a small update, first endpoints of the new API are now available starting with 2.2.0-Beta1:

We are focusing on covering what isn't available in APIv2 first, and after we have API feature parity with the GUI, we will start adding endpoints into APIv3 which are currently covered in v2.

As always, any feedback and suggestions are very welcomed.
Posts: 5
Joined: Tue Jan 18, 2022 3:17 am

Tue Jan 18, 2022 3:46 am

Hi Tomas,

Had a quick review of the APIv3 and it all looks reasonable. A minor comment on API style.

1. POST /api/v3/zones/{uuid}/proxy:remote_core
IMHO this is an unusual style for a REST API, it's like you're using an operation style here for setting a property, I wonder why we can't use PUT to update this attribute like the name and description?
This is in contrast to your use of "operation style/batch" endpoints like POST /api/v3/devices:tag which seem reasonable and useful to me which also use POST to entity:operation.

2. Feature request:
Please can we have a helper endpoint like the latest config backup from v2, e.g.
GET /api/v3/devices/{uuid}/backups/latest

Background: we use the API to pull down either the latest backup or with a client side script, start a config backup, then poll for a newer backup to be available then pull the newest backup down. It looks like the APIv3 will be able to retrieve backup job status so this will make this implementation cleaner (we have to use heuristics based on backup age and timeouts to determine if backup on demand works).

3. Feature request:
Official Python API.

Great to see this work happening!

Posts: 198
Joined: Thu Aug 05, 2021 6:35 pm

Tue Jan 18, 2022 4:22 pm

Hello Sam,

Let me add some commentary to the points you mentioned.

1. The reason we use POST for changing proxy type is that compared to something like updating device name/description it is (from the backend point of view) considerably more complex and triggers processes which are not triggered when PUT is used.

2. Yes, we will add it. Currently we are focusing on covering all the remaining functionality in Unimus which wasn't covered by v2 and after that we will start reworking existing calls present in v2 to v3 version of API, and of course we will make sure it will supported in v3 as it is currently in v2.

3. Feature request passed to our team, and they will look into it. ;)
Posts: 1
Joined: Sat Sep 16, 2023 5:55 am

Sat Sep 16, 2023 6:05 am


A nice feature would to be add a way to add or override variables when doing an API call to device push. That way, I can preset a command with variable that are sent at the API call.

For example: one could have a preset to add a TCP port forward. You could parametized the API call to change the port dynamically.

Let me know if that doesn't make sense.

Posts: 36
Joined: Fri Jun 09, 2023 6:47 pm

Mon Sep 18, 2023 4:51 pm


Thank you for your suggestion. We will definitely add it into our road-map.
Posts: 10
Joined: Fri Sep 23, 2022 1:09 pm

Wed Dec 20, 2023 10:06 pm


I think the suggestions look ok, although I could not see any plans for adding user accounts in API v3. That is a tedious task when using many tags for user access. Maybe the reason is that you are doing re-work on the whole RBAC and that it just is to complicated to add that to the API in the immediate future?

Kind Regards,

Post Reply