You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@guacamole.apache.org by "Najib ." <ao...@outlook.com> on 2023/06/22 16:08:26 UTC
REST API Suggestions
Its really awesome that Guacamole can be called using REST API, this makes it incredibly powerful and flexible. However there some pain points and improvements possible
1. The connection and connection group response bodies are a rather big JSON. They don’t use the array type and the keys contain the actual values of the connection identifier. Any JSON parser will panic trying to decipher them. Is there a reason why such JSON file is created for these two types whereas others respect proper JSON formatting? See below for what a better reponse body would look like.
2. I couldn’t find it but there seems to be no API endpoint for forcing a logout for the user. I know you can kill any or all sessions for a user and their connection permissions rendering them seeing an empty page. However if the IdP also blocks them from getting a new token this can never happen in the current situation as long as the user stays logged on. A logout API call would solve this.
I would like to add this is not complaining about Guac. I truly love this solution and all the people contributing to it its truly the silent MVP in the tech world and you guys are doing amazing work. But when you truly love something you also want it to become better.
Before;
{
"11": {
"name": "AD Jump Hosts - External Users",
"identifier": "11",
"parentIdentifier": "ROOT",
"type": "ORGANIZATIONAL",
"activeConnections": 0,
"attributes": {
"max-connections": null,
"max-connections-per-user": "10",
"enable-session-affinity": ""
}
},
"1": {
"name": "Emergency Access - AD Jump Hosts",
"identifier": "1",
"parentIdentifier": "ROOT",
"type": "ORGANIZATIONAL",
"activeConnections": 0,
"attributes": {
"max-connections": null,
"max-connections-per-user": null,
"enable-session-affinity": ""
}
}
}
After:
[
{
"name": "My connection Group A",
"identifier": "11",
"parentIdentifier": "ROOT",
"type": "ORGANIZATIONAL",
"activeConnections": 0,
"attributes": {
"max-connections": null,
"max-connections-per-user": "10",
"enable-session-affinity": ""
}
},
{
"name": "My connection Group B",
"identifier": "1",
"parentIdentifier": "ROOT",
"type": "ORGANIZATIONAL",
"activeConnections": 0,
"attributes": {
"max-connections": null,
"max-connections-per-user": null,
"enable-session-affinity": ""
}
}
]
Re: REST API Suggestions
Posted by Nick Couchman <vn...@apache.org>.
On Thu, Jun 22, 2023 at 4:05 PM Caleb Coverdale
<ca...@me.com.invalid> wrote:
>
> I know I don’t have much skin in the game here, but I also agree with this change.
>
>
> Having to convert it back into the proposed format as we speak.
>
> This would definitely change the way things are called for the better.
>
Could you also clarify what you're doing with the data and why you
need to convert from Object-based to Array-based storage (and back)?
-Nick
---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@guacamole.apache.org
For additional commands, e-mail: user-help@guacamole.apache.org
Re: REST API Suggestions
Posted by Caleb Coverdale <ca...@me.com.INVALID>.
I know I don’t have much skin in the game here, but I also agree with this change.
Having to convert it back into the proposed format as we speak.
This would definitely change the way things are called for the better.
>
> On Jun 22, 2023, at 10:08 AM, Najib . <ao...@outlook.com> wrote:
>
>
> Its really awesome that Guacamole can be called using REST API, this makes it incredibly powerful and flexible. However there some pain points and improvements possible
>
> The connection and connection group response bodies are a rather big JSON. They don’t use the array type and the keys contain the actual values of the connection identifier. Any JSON parser will panic trying to decipher them. Is there a reason why such JSON file is created for these two types whereas others respect proper JSON formatting? See below for what a better reponse body would look like.
> I couldn’t find it but there seems to be no API endpoint for forcing a logout for the user. I know you can kill any or all sessions for a user and their connection permissions rendering them seeing an empty page. However if the IdP also blocks them from getting a new token this can never happen in the current situation as long as the user stays logged on. A logout API call would solve this.
>
> I would like to add this is not complaining about Guac. I truly love this solution and all the people contributing to it its truly the silent MVP in the tech world and you guys are doing amazing work. But when you truly love something you also want it to become better.
>
> Before;
> {
> "11": {
> "name": "AD Jump Hosts - External Users",
> "identifier": "11",
> "parentIdentifier": "ROOT",
> "type": "ORGANIZATIONAL",
> "activeConnections": 0,
> "attributes": {
> "max-connections": null,
> "max-connections-per-user": "10",
> "enable-session-affinity": ""
> }
> },
> "1": {
> "name": "Emergency Access - AD Jump Hosts",
> "identifier": "1",
> "parentIdentifier": "ROOT",
> "type": "ORGANIZATIONAL",
> "activeConnections": 0,
> "attributes": {
> "max-connections": null,
> "max-connections-per-user": null,
> "enable-session-affinity": ""
> }
> }
> }
>
> After:
> [
> {
> "name": "My connection Group A",
> "identifier": "11",
> "parentIdentifier": "ROOT",
> "type": "ORGANIZATIONAL",
> "activeConnections": 0,
> "attributes": {
> "max-connections": null,
> "max-connections-per-user": "10",
> "enable-session-affinity": ""
> }
> },
> {
> "name": "My connection Group B",
> "identifier": "1",
> "parentIdentifier": "ROOT",
> "type": "ORGANIZATIONAL",
> "activeConnections": 0,
> "attributes": {
> "max-connections": null,
> "max-connections-per-user": null,
> "enable-session-affinity": ""
> }
> }
> ]
>
>
Re: REST API Suggestions
Posted by Nick Couchman <vn...@apache.org>.
On Thu, Jun 22, 2023 at 4:23 PM Michael Jumper <mj...@apache.org> wrote:
>
> On 6/22/23 09:26, Nick Couchman wrote:
> > On Thu, Jun 22, 2023 at 12:08 PM Najib . <ao...@outlook.com> wrote:
> >>
> >> Its really awesome that Guacamole can be called using REST API, this makes it incredibly powerful and flexible. However there some pain points and improvements possible
> >>
> >> The connection and connection group response bodies are a rather big JSON. They don’t use the array type and the keys contain the actual values of the connection identifier. Any JSON parser will panic trying to decipher them. Is there a reason why such JSON file is created for these two types whereas others respect proper JSON formatting? See below for what a better reponse body would look like.
> >
> > Working backward:
> > * "Any JSON parser will panic trying to decipher them" - I don't think
> > so - in fact, these very REST API responses are used by the browser
> > itself to drive the web application. So there's at least one parser
> > that _does not_ currently choke on them :-). Also, there's nothing
> > wrong or non-standard about the JSON - it's perfectly valid, perfectly
> > legitimate JSON. If a JSON parser is choking on the response, then it
> > seems that it is unable to parse valid JSON, or simply does not have
> > the resources to handle it. Using the identifier simply makes it an
> > object, not an array - but it's still "good" JSON.
> > * "They don’t use the array type and the keys contain the actual
> > values of the connection identifier." - Yes, in fact, that's exactly
> > the reason it is implemented this way. That way, if you want to get a
> > specific connection or connection group, all you have to do is go get
> > the specific object and you don't have to loop through the entire
> > array looking for the correct identifier.
>
> Najib, can you clarify further why object vs. array would be a
> substantial cause of difficulty for applications consuming the REST API?
>
> As Nick notes above, there is a technical reason we prefer to return
> objects instead of arrays for responses that contain collections of
> uniquely-identified objects. Barring a solid technical reason to migrate
> to arrays, I would definitely be against changing the REST API in this way.
>
> The only technical reasons that occur to me for an array being more
> ideal than an object in a REST API response would be:
>
> * Cases where order is significant.
And, even in this case, I would think the objects could be sorted,
either by the back-end before returning them to the API, or by the
consumer, no? Obviously that requires additional processing,
particularly if done on the client-side after getting all of the
results, my point is just that it's technically do-able.
I suppose if you were trying to do something like loop through all
connections for the purpose of listing them or performing an operation
on all connections the array would be marginally easier to deal with,
but looping through objects should be doable, particularly in common
REST API client languages (JavaScript and Python come to mind).
-Nick
---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@guacamole.apache.org
For additional commands, e-mail: user-help@guacamole.apache.org
Re: REST API Suggestions
Posted by Michael Jumper <mj...@apache.org>.
On 6/22/23 09:26, Nick Couchman wrote:
> On Thu, Jun 22, 2023 at 12:08 PM Najib . <ao...@outlook.com> wrote:
>>
>> Its really awesome that Guacamole can be called using REST API, this makes it incredibly powerful and flexible. However there some pain points and improvements possible
>>
>> The connection and connection group response bodies are a rather big JSON. They don’t use the array type and the keys contain the actual values of the connection identifier. Any JSON parser will panic trying to decipher them. Is there a reason why such JSON file is created for these two types whereas others respect proper JSON formatting? See below for what a better reponse body would look like.
>
> Working backward:
> * "Any JSON parser will panic trying to decipher them" - I don't think
> so - in fact, these very REST API responses are used by the browser
> itself to drive the web application. So there's at least one parser
> that _does not_ currently choke on them :-). Also, there's nothing
> wrong or non-standard about the JSON - it's perfectly valid, perfectly
> legitimate JSON. If a JSON parser is choking on the response, then it
> seems that it is unable to parse valid JSON, or simply does not have
> the resources to handle it. Using the identifier simply makes it an
> object, not an array - but it's still "good" JSON.
> * "They don’t use the array type and the keys contain the actual
> values of the connection identifier." - Yes, in fact, that's exactly
> the reason it is implemented this way. That way, if you want to get a
> specific connection or connection group, all you have to do is go get
> the specific object and you don't have to loop through the entire
> array looking for the correct identifier.
Najib, can you clarify further why object vs. array would be a
substantial cause of difficulty for applications consuming the REST API?
As Nick notes above, there is a technical reason we prefer to return
objects instead of arrays for responses that contain collections of
uniquely-identified objects. Barring a solid technical reason to migrate
to arrays, I would definitely be against changing the REST API in this way.
The only technical reasons that occur to me for an array being more
ideal than an object in a REST API response would be:
* Cases where order is significant.
* Cases where objects do not have unique identifiers.
but neither of those would apply here.
- Mike
---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@guacamole.apache.org
For additional commands, e-mail: user-help@guacamole.apache.org
Re: REST API Suggestions
Posted by Nick Couchman <vn...@apache.org>.
On Thu, Jun 22, 2023 at 12:08 PM Najib . <ao...@outlook.com> wrote:
>
> Its really awesome that Guacamole can be called using REST API, this makes it incredibly powerful and flexible. However there some pain points and improvements possible
>
>
>
> The connection and connection group response bodies are a rather big JSON. They don’t use the array type and the keys contain the actual values of the connection identifier. Any JSON parser will panic trying to decipher them. Is there a reason why such JSON file is created for these two types whereas others respect proper JSON formatting? See below for what a better reponse body would look like.
Working backward:
* "Any JSON parser will panic trying to decipher them" - I don't think
so - in fact, these very REST API responses are used by the browser
itself to drive the web application. So there's at least one parser
that _does not_ currently choke on them :-). Also, there's nothing
wrong or non-standard about the JSON - it's perfectly valid, perfectly
legitimate JSON. If a JSON parser is choking on the response, then it
seems that it is unable to parse valid JSON, or simply does not have
the resources to handle it. Using the identifier simply makes it an
object, not an array - but it's still "good" JSON.
* "They don’t use the array type and the keys contain the actual
values of the connection identifier." - Yes, in fact, that's exactly
the reason it is implemented this way. That way, if you want to get a
specific connection or connection group, all you have to do is go get
the specific object and you don't have to loop through the entire
array looking for the correct identifier.
* "The connection and connection group response bodies are a rather
big JSON." - In the example you posted below, the size of the returned
data in the "After" example is _exactly the same_ as the size of the
data in the "Before" example (how it's currently implemented. So,
there does not appear to be any size reduction in the actual data, and
the search time (O(n)) to locate a specific connection or connection
group would be much longer, as you'd have to loop through potentially
every item before finding it, rather than indexing it directly.
> I couldn’t find it but there seems to be no API endpoint for forcing a logout for the user. I know you can kill any or all sessions for a user and their connection permissions rendering them seeing an empty page. However if the IdP also blocks them from getting a new token this can never happen in the current situation as long as the user stays logged on. A logout API call would solve this.
If you know the token you can force a logout using:
DELETE /api/tokens/{token}
See:
https://github.com/apache/guacamole-client/blob/master/guacamole/src/main/java/org/apache/guacamole/rest/auth/TokenRESTService.java
That said, I do not believe there is a way within the current REST API
to get a list of all users and tokens - you'd have to locate that,
first, before you can force the logout. I could be wrong about this,
but I don't see a way off the top of my head.
>
>
>
> I would like to add this is not complaining about Guac. I truly love this solution and all the people contributing to it its truly the silent MVP in the tech world and you guys are doing amazing work. But when you truly love something you also want it to become better.
We definitely appreciate the feedback and discussion on this - we have
a great community and the discussion, here, very much helps to drive
the ideas about how the project progresses in the future. Thanks for
being involved in the community!
-Nick
---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@guacamole.apache.org
For additional commands, e-mail: user-help@guacamole.apache.org