[Draft] Unimus API v3 - feedback wanted

Beta release announcements and discussion around them
Post Reply
User avatar
Tomas
Posts: 1099
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!
ptorbjornsson
Posts: 18
Joined: Tue Aug 11, 2020 12:08 pm

Mon Sep 13, 2021 7:08 am

Hi,

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
Tomas
Posts: 1099
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:
viewtopic.php?f=4&t=1395

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.
smallsam
Posts: 3
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!

Sam
Vik@Unimus
Posts: 95
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. ;)
Post Reply