If we consider the fact that orgs, teams and users are similar types of resources or entities on the same tree (and have some common functionality), the way we currently hang off the child listing, nesting functionality & search could be simplified.
e.g. here is how we currently retrieve teams children using GET
/authorization/teams/{id}/users
/authorization/teams/{id}/nested (which is essentially teams/{id}/teams)
/authorization/teams/{id}/policies
/authorization/teams/{id}/users/search
this pattern is repeated for orgs, users etc.
could it be simplified using a combination of filtering on GET, and use of payloads on PUT on the entity without having to add extra routes?
for example, a GET on teams/{id} already lists users and policies in the response body in an array (but not nested teams), if we added child teams as another array we could simply filter the returned object using some sort of filter GET param and remove the extra routing to access those children individually?
e.g. teams/{id}?type=users||policies||teams||all(default)
This would only retrieve the specific child list specified
If we did it this way we could have options to sort, search on the entire child list or the specified filtered list and pagination would remain consistent, reducing lots of repeated code.
e.g.
teams/{id}?type=users&search=xyz&page=1 could be an example to list all users, filter the results based on search, and limiting to view page 1 of the results
We could also pout in filters for listing parents objects to look up a level in the structure, in the same way we look for nested children, for assistance with tree traversal on a UI for example
For a put request, the payload could contain, id and type of whatever child object needs to be nested, and details of the object itself, a command, unnest could be supplied as a parameter to disassociate policies, users, team children also in the same way.
To delete something entirely the DELETE command should be used against the specific entity ID at the root. If ids were globally unique we would not need to specify a type when deleting, if constraints on id are limited by table we would need to specify delete with a type or within the entity route.
It would also allow us to perform routing based on paths to teams (as per issue: https://github.com/nearform/udaru/issues/484) and would remove the need for endpoints such as /authorization/teams/{id}/users/search, which we may need to start repeating for sub policies, sub teams and so on
If we consider the fact that orgs, teams and users are similar types of resources or entities on the same tree (and have some common functionality), the way we currently hang off the child listing, nesting functionality & search could be simplified.
e.g. here is how we currently retrieve teams children using GET /authorization/teams/{id}/users /authorization/teams/{id}/nested (which is essentially teams/{id}/teams) /authorization/teams/{id}/policies /authorization/teams/{id}/users/search
this pattern is repeated for orgs, users etc.
could it be simplified using a combination of filtering on GET, and use of payloads on PUT on the entity without having to add extra routes?
for example, a GET on teams/{id} already lists users and policies in the response body in an array (but not nested teams), if we added child teams as another array we could simply filter the returned object using some sort of filter GET param and remove the extra routing to access those children individually?
e.g. teams/{id}?type=users||policies||teams||all(default)
This would only retrieve the specific child list specified
If we did it this way we could have options to sort, search on the entire child list or the specified filtered list and pagination would remain consistent, reducing lots of repeated code.
e.g. teams/{id}?type=users&search=xyz&page=1 could be an example to list all users, filter the results based on search, and limiting to view page 1 of the results
We could also pout in filters for listing parents objects to look up a level in the structure, in the same way we look for nested children, for assistance with tree traversal on a UI for example
For a put request, the payload could contain, id and type of whatever child object needs to be nested, and details of the object itself, a command, unnest could be supplied as a parameter to disassociate policies, users, team children also in the same way.
To delete something entirely the DELETE command should be used against the specific entity ID at the root. If ids were globally unique we would not need to specify a type when deleting, if constraints on id are limited by table we would need to specify delete with a type or within the entity route.
It would also allow us to perform routing based on paths to teams (as per issue: https://github.com/nearform/udaru/issues/484) and would remove the need for endpoints such as /authorization/teams/{id}/users/search, which we may need to start repeating for sub policies, sub teams and so on
Just opening up for discussion.