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!
[Draft] Unimus API v3 - feedback wanted
-
ptorbjornsson
- Posts: 23
- Joined: Tue Aug 11, 2020 12:08 pm
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!
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!
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.
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.
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
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: 198
- Joined: Thu Aug 05, 2021 6:35 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.
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.
Hello,
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.
Thanks,
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.
Thanks,
Hi,
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,
//Dan
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,
//Dan
Hello everyone.
In 2.5.1, we did a bunch of work on existing APIv3 endpoints. There were 2 main goals we wanted to achieve:
1) introduce both enum and string values to endpoints which used enums
2) unify search handling, and introduce ability to use both AND or OR search functions in the AP
For point 1, this is rather simple. We are adding both enum and string value representations to all enum-type objects in the API. This will give you the option to use string representations of enums in the API.
For search (point 2), we added the option to specify AND or OR search functions in the API between fields properties. There were inconsistencies in the API as to what searches would be ORed and what would be ANDed. We decided to unify this to the following:
- search will use OR between multiple properties
- within a property with multiple provided values, OR will be used by default, but you now have an option to specify AND
If you want to do AND between properties, you can fire multiple API requests, each with its own property filters, and AND the resulting data yourself.
This might be best shown using an example. Let's say you do an APIv3 LIST request to the "zone" endpoint. You specify as search criteria "names" and also "numbers". So you provided 2 properties to search with. By default, within properties, OR will be used. But OR will also be used between properties. In effect, you will get a hit if any of the provided criteria match. BUT, you can now also specify AND within properties. As mentioned above, between properties, OR will always be used.
All in all, here are the APIv3 changes coming in 2.5.1:
And here is what was added to the APIv3 in 2.5.1:
In 2.5.1, we did a bunch of work on existing APIv3 endpoints. There were 2 main goals we wanted to achieve:
1) introduce both enum and string values to endpoints which used enums
2) unify search handling, and introduce ability to use both AND or OR search functions in the AP
For point 1, this is rather simple. We are adding both enum and string value representations to all enum-type objects in the API. This will give you the option to use string representations of enums in the API.
For search (point 2), we added the option to specify AND or OR search functions in the API between fields properties. There were inconsistencies in the API as to what searches would be ORed and what would be ANDed. We decided to unify this to the following:
- search will use OR between multiple properties
- within a property with multiple provided values, OR will be used by default, but you now have an option to specify AND
If you want to do AND between properties, you can fire multiple API requests, each with its own property filters, and AND the resulting data yourself.
This might be best shown using an example. Let's say you do an APIv3 LIST request to the "zone" endpoint. You specify as search criteria "names" and also "numbers". So you provided 2 properties to search with. By default, within properties, OR will be used. But OR will also be used between properties. In effect, you will get a hit if any of the provided criteria match. BUT, you can now also specify AND within properties. As mentioned above, between properties, OR will always be used.
All in all, here are the APIv3 changes coming in 2.5.1:
All in all, here is a full list of changes to existing endpoints in APIv3 in 2.5.1:For search, added option to specify if AND or OR should be used within properties if multiple property values are provided (OR by default)
For search, OR logic is used between properties if multiple search properties are provided
All enum type fields now have 2 values - Enum and String, adding option to use string representation in the API
Added object descriptions to multiple endpoints that were missing them
Code: Select all
credential - create - request -> rename type to typeEnum
list - request -> rename credentialsTypes to typeEnums
- response -> rename credentialsType to typeEnum
job status - list - request -> rename jobType to jobTypeEnum
- response -> rename jobType to jobTypeEnum
push - run - request -> advanced settings -> rename promptMatchingMode to promptMatchingModeEnum
tag - create - request -> rename backupStrippingPolicy to backupStrippingPolicyEnum
- list - request -> rename strippingPolicies to backupStrippingPolicyEnums
- response -> rename backupStrippingPolicy to backupStrippingPolicyEnum
zone - create - request -> rename proxyType to proxyTypeEnum
- list - request -> rename proxyTypes to proxyTypeEnums
- response -> rename proxyType to proxyTypeEnum
zone default searching between properties was AND, fixed to OR
Code: Select all
credential - create - description -> enhancement
- list - request -> added searching by typeStrings
-> added valueOperand (AND/OR- by default)
- response -> added typeString
- description -> enhancement
job status - list - request -> added jobTypeStrings
- response -> added jobTypeString
-> added taskStateString
- description -> enhancement
push - run - description -> enhancement
tag - create - description -> enhancement
- list - request -> added backupStrippingPolicyStrings
-> added valueOperand (AND/OR- by default)
- response -> added backupStrippingPolicyString
- description -> enhancement
zone - create - description -> enahncement
- list - request -> added proxyTypeStrings
-> added valueOperand (AND/OR- by default)
- response -> added proxyTypeString
- description -> enhancement